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PREFACE 


APL was first defined by K. E. Iverson in A Programming Language 
(Wiley, 1962) and has since been developed in collaboration with 

A. D. Falkoff and L. M. Breed. APL has been adapted into a conver- 
sational programming system and has been implemented on a variety of 
computers. 


APL is a very concise programming language especially suitable for 
handling numeric and character array-structured data. Despite its 
mathematically concise and consistent format, APL is intended to be 
used as a general data-processing language as well as a mathematician's 
tool. The language is flexible enough to solve problems in text- 
handling and commercial data processing as concisely and as easily as 
it can be used to solve problems in numerical mathematics and 
statistics. 


APL allows user-defined functions to be expressed with the same syntax 
as that used to express primitive language functions. This provides 
the user with an efficient and simple means of expanding the capabili- 
ties of the language to handle the requirements of any application 
area. 


Areas of current application include scientific data reduction and 
analysis, simulation and forecasting, financial modeling, design 
engineering, electric circuit analysis, engineering analysis, inven- 
tory and payroll management, data base manipulation, reservation sys- 
tems, automatic theorem proving, computer-assisted instruction (CAI), 
and student education (high school and college level) in programming 
and the structure of algorithmic processes. The applicability of 

APL as a complete conversational programming system is unlimited. 


This manual presents an implementation of APL-11, a version of the 
APL language on the PDP-11l computer system. It should serve as a 
reference manual for all users of APL-1l. This is not intended to be 
used as a language primer. The new APL user may want to refer to 

any of several good primers available for basic instruction in the 
language. 


This manual is divided into six chapters and five appendixes. Infor- 
mation is structured as shown on the following page: 


ix 


Chapter 
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Contents 


APL-11 operating environment 

APL terminals and character set 

Starting, ending, and interrupting the APL session 
Keyboard editing procedures 


APL language introduction and background information 
Primitive scalar and mixed functions 


Defining, editing, and executing user-defined 
functions 


APL system variables and I-beam functions 
APL system commands 


APL-11 file system 


Appendixes A through D provide summary information on 4PL functions, 
system commands, I-beams and system variables, and error messages 
respectively. Appendix E describes procedures for installing 4PL 

in the RT-11, RSTS/E, RSX-11M, and IAS operating environments. 
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THE APL-11 OPERATING ENVIRONMENT 


CHAPTER 1 


THE APL-1l OPERATING ENVIRONMENT 


1.1 APL ON THE PDP-11 


The APL-11 system has been implemented as a language interpreter on 
the PDP-ll. It operates on a wide range of hardware processors and 
has been designed to run under any of four operating systems: RT-1l, 
RSTS/E, RSX-11M, or IAS. This chapter introduces API-11 and illus- 
trates differences in initiating, terminating, and interrupting an 
APL session under these operating systems. 


The APL-11 interpreter has been designed to be as flexible as possible 
to meet the needs of a variety of different users. Users can select 
from a range of system options. A customized version of the APZI-11 
system is distributed, reflecting the following installation-dependent 
characteristics: 


® type of PDP-11 processor being used 

® availability of floating-point hardware (FPP or FIS) on 
the PDP-11 processor 

e operating system (RT-1l1, RSTS/E, RSX-11M, or IAS) under 
which AP£Z-11 will run 

e arithmetic precision desired (single-precision or double- 
precision) 


If an installation's PDP-1ll processor is not a PDP-11/70 or another 
processor that offers extended instructions (for example, the 
PDP-11/45 or a processor supporting EIS), the APL software simulates 
these extended instructions by generating a set of macros. Similarly, 
if the processor does not support the FPP hardware, the APL software 
Simulates the capabilities of this hardware by assembling a software 
floating-point package with the APZ interpreter. 


The RT-1l, RSTS/E, RSX-11M, and IAS operating systems provide APL 
users with most of the standard features of the PDP-11 single-user 
and time-sharing environments. API-11 is configured for single-user 
access under RT-1ll and RSTS/E, or as a task under RSX-11M and IAS; 
thus, the interpreter is heavily overlaid to increase the size of the 
user workspace. 


A single-precision APL-11 system provides an accuracy of approximately 
seven digits, and a double-precision system offers an accuracy of about 
16 digits. If a single-precision system is selected, floating-point 
numbers are four bytes long. If a double-precision system is selected, 
floating-point numbers are eight bytes long. 


1.2 FILES IN THE APL SYSTEM 


This section describes the special characteristics of workspaces and 
data files in the APL-11l environment. 


1.2.1 APL Workspaces 


An APL workspace is a part of the user's memory area that 1s — Sen 
store functions and variables defined by the APL user, and ures cee 
temporary results obtained while executing APL statements. ak e oo ee 
symbol table is stored in the workspace, along with the state tndtea : ’ 
an internal stack that may be accessed to determine the execution status 
of any defined function in the workspace. Workspaces can be cleared, 
named, erased, or saved on a secondary-storage device, and retrieved 
from that device at a later time. 


When the user begins an APL session, a special workspace called the 

elear workspace is made available for his use. This workspace contains 

no defined functions or variables, has a clear symbol table and state 
indicator, and has no open files. The clear workspace has a variety ba 
of standard system values associated with it, including the following: 


@ index origin of l 


® output line length of 72 (the default terminal width is 
used for RSTS/E) 


e six (single-precision) or ten (double-precision) significant 
digits 


® comparison tolerance (fuzz) of 52 7 (single-precision) or ~ 
5E 15 (double-precision) 


These values may be changed by the user during the current APL 
session. If a workspace is saved, the user-specified values are 
stored along with the workspace and will be in effect when the saved 
workspace is retrieved at a later time. 


The workspace currently available to the user is known as the active 
workspace, All functions and variables defined during the current 
APL session are stored in this workspace. The active workspace may 
be stored as a file on a PDP-11 secondary-storage device, such as 
disk, floppy disk, DECtape, and magnetic tape. It may be saved in 
core-image format by the )SAVE system command (Section 5.2.3). The 
user may assign the active workspace a name by the )WSID system 
command (Section 5.2.2) and may override this name, if desired, when 
the workspace is saved. 


Once an APL workspace has been saved on secondary storage, it may be 
deleted by the )DROP system command (Section 5.2.6) or retrieved to 
function as the active workspace once again. If the file has been 
saved, it must be retrieved by the )LOAD system command (Section 5.2.4). 
Data from the workspace may be copied into the current workspace by 

the )COPY and PCOPY system commands (Sections 5.3.6 and 5.3.7). The 
maximum size of an APL workspace depends upon the operating system and 
the amount of memory in the system. 


1.2.2 APL Data Files 


In the APL~-1l system, data files may be stored on a variety of devices, 
including disk, floppy disk, DECtape, and magnetic tape. Two types of 
data files are supported by APL-11: 


e ASCII sequential 
® random access 


ASCII sequential files are line-oriented sequential files that may 
be read and written by APL, by the MACRO Assembler, and by a variety 
of other language processors. ASCII sequential files may also be 
created and modified by RT-11, RSTS/E, RSX-11M, and IAS text 
editors. 


Random=access files may be read and written in a non-sequential fashion. 
When accessing the file, the user identifies the particular byte or data 
value to be read or written and specifies the format of that value. 

Data may be specified as ASCII, byte, integer, APL character, single- 
precision floating-point, or double-precision floating-point quantities. 
Random-access mode allows the user to construct records containing 
values of several different data types. It also facilitates the use of 
random-access data files created by other language processors or systems. 


The file operators and system commands implemented as part of the APZ-11 
file system are described in detail in Chapter 6. 


1.3 APL HARDWARE 


The user interacts with APL by means of a typewriter-like terminal. 

The APL language supports the use of a special character set, in which 
Greek letters and a variety of other special characters represent APL 
language operators. Examples of such special characters include pr 

1, O, V, and «. Several terminals available to API-11 users provide 
keyboards on which the full APL character set may be utilized. Stan- 
dard ASCII terminals may also be used with APL. On ASCII terminals, 

the special APL symbols are represented by means of keyword mnemonics, 
described in Section 1.4. The user selects the APL or ASCII character 
set at the time that he begins the current APL session (see Section 1.5). 


Table 1-1 lists the terminals supported by the PDP-11 computer system 
for use with APL-11. The second column of this table indicates whether 
or not the special APL character set is represented on the terminal 
keyboard. The third column lists the terminal designator that must be 
entered at the time that the APL session begins (see Section 1.5). 


Table l-1 
APL Terminals 


Any standard ASCII terminal ASCII 
without the APL character set 


DECwriter II model LA37 with APL/ASCII 


APL option 


Tektronix (®) 4013 or 4015 APL/ASCII 
terminal 


(®) Tektronix is a registered trademark of Tektronix, Inc. 
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1.3.1 APL Terminals 


The terminal keyboard illustrated below may be used in either ASCII or 
APL mode. It supports the full APL character set: all characters on 
this keyboard are received and interpreted by APL. Note that letters, 
numbers, and some of the special characters appear in the conventional 
keyboard positions. The letters print only in upper-case and are pro- 
duced only when the keyboard is not shifted. The full APL character 
set is described in Table 1-2, included in Section 1.4. 
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Figure 1-1 The APL Keyboard (LA37 Terminal) 


1.3.2 ASCII Terminals 


ASCII terminals do not support the use of the special APL character 

set illustrated in the APL keyboard shown in Section 1.3.1. If the user 
has an ASCII terminal or is operating in ASCII mode on an APL terminal, 
he must use keyboard mnemonics in place of the special APL symbols 

not available in ASCII. To represent the APZ rho symbol (p), for ex- 
ample, the user enters the mnemonic .RO. The .GO mnemonic is equiva- 
lent to the APL right-arrow (+), and the .EP mnemonic is equivalent to 
the APL epsilon (ce). A summary of the mnemonic equivalents for all 

APL characters is provided in Table 1-2. 


Tf the user has an ASCII terminal, but erroneously selects the APL 
character set by specifying an incorrect terminal designator, he can 
terminate the APL session by typing the )OFF system command, replacing 
the left parenthesis with a double quote character, as in the 
following: 


"off 


Note that lower-case characters must be used. 


NOTE 


Because the keyword mnemonics are charac- 
terized by the presence of a period (.) 

as the first character, the period should 
not be used to separate the workspace 
filename and extension name in ASCII mode. 
The comma (,) should be used instead. 
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1.4 THE APL CHARACTER SET 


Table 1-2 summarizes all characters used in the APL system. The first 
column lists the characters found on APL terminal keyboards. The sec- 
ond column provides a list of the corresponding characters available 

on ASCII terminals. The third column lists keyword mnemonics used to 


- represent APL symbols not available on the ASCII keyboard. The fourth 


column supplies the names commonly associated with the APL characters, 
with upper-case letters indicating the origin of the mnemonic 
representation. 


The second section of the table lists APZ overstruck characters. These 
are characters constructed by overstriking two distinct characters on 
the terminal keyboard. For example, the logarithm symbol (@) is formed 
by overstriking the circle (0) with the exponentiation symbol (*). The 
grade up symbol (4) is formed by overstriking the delta symbol (A) with 
the straight line (|) used to represent residue or absolute value. To 
express an overstruck character on an APL terminal, the user types one 
character of the overstrike combination, ‘then presses the backspace key, 
then types the other character of the combination. The order is not 
significant. On ASCII terminals, all overstruck characters are repre- 
sented by alternate single-strike characters or by keyword mnemonics. 


Table 1-2 
APL Character Set 


Single-Strike Characters 


+ 


add 

alphabetics 

ANd 

assignment 
concatenate, comma 
colon 

decimal point 
Divide 

equal to 

expand 
exponentiate 
Greater Than 

left bracket 

left parenthesis 
Less Than 
multiply 

numerics 

quote string 
question (roll and deal) 
reduce 

right bracket 
right parenthesis 
semicolon 

subtract 

Take 

UnderScore 

residue (ABsolute value) 
Alpha 

quad (BoX) 

CEiling (maximum) 


hy 


+> 1 + 
NS 


te A AV + I cee 


\ 
* 
> 
[ 
( 
< 


jen) 


> be wins =! 
ie) 


oO 


>i Gon =) 


aOe-} 
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Table 1-2 (Cont.) 
APL Character Set 


Single-Strike Characters 


drop (Down Arrow) 
Dieresis 

DEcode 

DeL 

DiaMond 

Down Union 
ENcode 

EPsilon 

FLoor 

Greater than or Equal 
GO to (branch) 
Tota 

Left Brace 

delta (Lower Del) 
Less than or Equal 
Left tack 

circle (Large 0) 
Left Union 

Not Equal to 
NeGation 

NoT 


Ik VOTAR AA + MOM AD OME 


Right Brace 
Right tack 
Rho 

Right Union 
jot (Small o) 
Up Union 


Overstruck Characters 


lamp 

factorial 

Dollar Sign 
Grade Down 
Grade Up 

I-Beam 
LoGarithm 

NaNd 

NOR 

Column expansion 
Column Rotate 
Column reduction 
Divide Quad 
Input Quad 
Output Quad 

out 

Protected Del 
set file Pointer 
Quad Del 

Quote Quad 
Subset 

Contains 


w 
Vv 
i 
_ 
p 
c 
° 
U 


vin SSS tar Oort 2 @HPdmerdD 
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Table 1-2 (Cont.) 
APL Character Set 


Overstruck Characters 


ReVersal 


TRanspose 

execute 

ForMat 

underscored alphabetics 
underscored del 





1.5 INTERACTING WITH APL 


This section describes how the APZ-11 user establishes communication 
with APL and concludes or interrupts an APL session. It provides 
separate descriptions of operating procedures in the RT-1l, RSTS/E, 
RSX-11M, and IAS operating systems. 


1.5.1 RT-11 Operating Procedures 


API-11 runs as a single-user program in the RT-11 operating system. 
An example of invoking APL, performing a function, and ending an APL 
session is included at the end of this section. 


To initiate interaction with APL, the user first establishes communica- 
tion with RT-l1l. The system displays the period prompt character, and 
the user enters the following command: 


-R APL 


and presses the RETURN key. The RETURN key must be pressed at the con- 
clusion of any monitor or APL statement to cause that statement to be 
transmitted. APL begins the session by asking about the user's 
terminal type: 


TERMINAL. . 


and waiting for a response. If the user types H (for HELP), APL dis- 
plays a description of the terminals currently supported by the system, 
and repeats the "TERMIWAL.." prompt - for example: 

RUN SAP L 

TERMINAL. +H 

GIVE THE AFFROFRIATE RESFONSE FOR YOUR TERMINAL 

RESFONSE YOUR TERMINAL 


LASS LA36 WITH AFL. CHARACTER SET OFTION 
4013 TEKTRONIX 4013 
TT ANY TERMINAL NOT HAVING AFL FONT 


TERMINAL « + 


The user selects the designator that is appropriate to his terminal 
type, and enters it as shown below: 


TERMINAL... TT 
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After receiving a valid terminal designator, APL responds with a sign- 
on greeting -- for example: 


WELCOME TO AFL/11 


It then supplies a clear workspace for use during the current APL 
session and displays the message: 


CLEAR WS 


The system indents six spaces to indicate that it is ready to accept 
user input. APL output results at the left margin, but automatically 
indents six spaces before unlocking the keyboard and allowing any user 
text to be entered. The system thus clearly differentiates between 
system and user entries. 


Under RT~11, an APL session may be concluded by means of either of the 
system commands shown below. 


Command Effect 


)OFF Ends the session, exits from APL, and 
returns to RT=-11 command level. 


)RUN filename Ends the session, exits from APL, and 
runs the program specified as an argu- 
ment in the )RUN command. 


These system commands are described in greater detail in Sections 5.5.1 
and 5.5.2. smI-beam 36 (Section 4.3.15) may also be used to terminate 
the APL session and return to RT-11 command level. With all of these 
commands and functions, APL automatically closes all open files before 
exiting from APL. 


The currently active workspace will not be preserved if )OFF, )RUN, or 
I-beam 36 is issued. If the user wants to save this workspace before 
terminating the APL session, he should store it on disk or on another 
secondary-storage device by issuing a )SAVE (Section 5.2.3) system 
command. 


The user may interrupt APZ without actually terminating the session 
and losing the active workspace. The following control characters are 
used in the RT=-11 system to interrupt APL. 


Character (s) Circumstances Effect 
CTRL/C APL is awaiting input Echoes a tC character 


and stops execution, 
displaying "EXECUTION 


STOP". Indents six 
spaces and awaits new 
APL input. 
CTRL/C, APL is executing a Echoes two tC characters, 
CTRL/C function, evaluating aborts output, and stops 
an expression, or execution, displaying 
performing output. "EXECUTION STOP" and 


the expression being 
evaluated. Indents six 
spaces and awaits new 
APL input. 
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Character(s) Circumstances Effect 


CTRL/O APL is performing Inhibits output until 
output on the terminal. completion of current 

output or until another 
CTRL/O is typed. The 
first CTRL/O echoes a 
+0 character, the sec- 
ond CTRL/O reenables 
output. 


NOTE 


On an APL terminal, CTRL/C echoes as 2n 
and CTRL/O echoes as 2e. 


In the following example, user responses are underlined. 


RUN AFL 
TERMINAL «+7 


WELCOME TO AFLZ11 V1.0 
CLEAR WS 
«DL LOOFER 
Cig LOOP? ALAtL 
C2] +GO_ 1.OOF 





C32 DL 
At 
LOOPER 

RE 


RESTARTING AFL 
LOOPERCID ALAtL 


973 


If three or more CTRL/C characters cause control to be returned to 
RT-11 command level, the user may reenter APL without beginning a new 
session by issuing the REENTER monitor command. The current active 
workspace is preserved, so the symbol table and all defined functions 
and variables remain intact. In general, the user should close all 
files before interrupting the APL session in this way. 


When APL is reentered, a restart message is displayed, and APL identi- 
fies the command or function line that was being evaluated when execu- 
tion was suspended. An up-arrow (t+) or caret (A) identifies the 
particular position in the line at which evaluation was interrupted, 
exactly as shown for the "EXECUTION STOP" case illustrated above. 


CAUTION 


If the user issues any command that runs 
another program (e.g., PIP) while at RT-11 
command level, the current workspace will 
be lost. 


1.5.2 RSTS/E Operating Procedures 


To initiate interaction with APL, the user first establishes communica- 
tion with RSTS/E, entering his project-programmer number and password 
in the normal way. The system displays a sign-on greeting and enters 
the standard BASIC language environment. BASIC displays a "Ready" 
message to indicate that it is ready to accept input. The user enters 
the following command: 


run Sapl 


and presses the RETURN key. The RETURN key must be pressed at the 
conclusion of any monitor or APL statement to cause that statement to 
be transmitted. If the RSTS/E installation has established the CCL 
command, APL, the user simply types: 


apl 


and presses the RETURN key. In either case, APL begins the session by 
asking about the user's terminal type: 


TERMINAL, , 


and waiting for a response. The user specifies the terminal being 
used during the current APL session, as illustrated in Section 1.5.1. 


After receiving a valid terminal designator, APL responds with a 
Sign-on greeting. As in the RT-1l environment, it supplies a clear 
workspace for use during the current APL session and displays the 
message: 


CLEAR WS 


The system indents six spaces to indicate that it is ready to accept 
user input. 


Under RSTS/E, an APL session may be concluded by means of one of the 
system commands shown below. 


Command Effect 


)OFF Ends the session, exits from APL, 
and returns to BASIC; BASIC displays 
the "Ready" message. 


)RUN ftlename Ends the session, exits from APL, 
and runs the program specified as an 
argument in the )RUN command. 


I-beam 36 may also be used to terminate the APZ session and return to 
BASIC. With all of these commands and functions, APL automatically 
closes all open files before exiting from APL. 


As in the RT~1l environment, APL does not automatically preserve the 
currently active workspace when )OFF, )RUN, or I-beam 36 is issued. 
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If the user wants to save this workspace before terminating the APL 
session, he should store it on disk or on another secondary storage 
device by issuing a )SAVE system command. 


In the RSTS/E operating system, the user may interrupt APL execution 
without actually exiting from APL. The following control characters 
are used to interrupt the APL session in the RSTS/E system. 


Character (s) Circumstances Effect 
CTRL/C APL is executing a Echoes a +C character, 
function, evaluating displays an EXECUTION 
an expression, await- STOP message and the 
ing input, or perform- expression being evalu- 
ing output. ated, indents six spaces, 


and awaits new APL input. 


CTRL/O APL is performing Inhibits output until 
output. completion of current 

output or until another 
CTRL/O is typed. The 
first CTRL/O echoes a 
+O character; the sec- 
ond CTRL/O reenables 
output. 


NOTE 


On an APL terminal, CTRL/C echoes as 2n 
and CTRL/O echoes as 2e. 


When APL is interrupted, it identifies the command or function line 
that was being evaluated when execution was suspended. An up-arrow 
(+) or caret (A) identifies the particular position in the line at 
which execution was interrupted, as illustrated in the following 
example. In this example, user responses are underlined. Note also 
that, because the terminal used in this example was an APL terminal, 
CTRL/C echoed as 2n, the equivalent of tC in the APL type face. 


d=11 
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1.5.3 RSX-11M Operating Procedures 


APE-11 runs as a task under the RSX-11M operating system. To initiate 
interaction with APL, the user first establishes communication with 
the RSX-1IM Monitor Console Routine (MCR). MCR displays the angle 
bracket prompt character (>), and the user enters the following 


command: 


>APL 


and presses the RETURN key. The RETURN key must be pressed at the 
conclusion of any monitor or APL command to cause that statement to 
be transmitted. As with RT-1ll and RSTS/E, APL begins the session by 
asking about the user's terminal type and awaiting a response (see 
Section 1.5.1 for examples of valid responses). APL then displays a 
sign-on greeting and supplies a clear workspace for use during the 
current APL session. This is shown in the example below. 


>APL 
TERMINAL. .TT 


WELCOME TO APL-11 VO2-01 
CLEAR WS 


The system indents six spaces to indicate that it is ready to accept 
user input. 


Under RSX-11M, an APL session may be concluded by means of the )OFF 
system command described in Section 5.5.1 I-beam 36 may also be used 
to terminate the APL session and return control to the Monitor Console 
Routine. If the user wants to save the currently active workspace 
before issuing )OFF or I-beam 36, he should use the )SAVE system 
command. 


1.5.4 IAS Operating Procedures 


APL~11 runs as a task under the IAS operating system. To initiate 
interaction with APL, the user first establishes communication with 
the IAS Program Development System (PDS). PDS displays the PDS> 
prompt, and the user enters the following command: 


PDS>APL 


and presses the RETURN key. The RETURN key must be pressed at the 
conclusion of any monitor or APL command to cause that statement to 

be transmitted. As with the other operating systems, APL begins the 
session by asking about the users' terminal type and awaiting a 
response (see Section 1.5.1 for examples of valid responses). APL then 
displays a sign-on greeting and supplies a clear workspace for use 
during the current APL session. This is shown in the example below. 


PDS>APL 
TERMINAL. .TT 


WELCOME TO APL-11 VO2-01 
CLEAR WS 


The system indents six spaces to indicate that it is ready to accept 
user input. 
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Under TAS, an APL session may be concluded by means of the )OFF system 
command, described in Section 5.5.1 I-beam 36 may also be used to 
terminate the APL session and return control to the Program Development 
System. If the user wants to save the currently active workspace 
before issuing )OFF or I-beam 36, he should use the )SAVE system 
command. 


1.6 KEYBOARD EDITING PROCEDURES 


This section summarizes the procedures for entering and correcting APL 
text at an APL or ASCII terminal. 


1.6.1 Immediate-Mode Editing Procedures 


The characters in an APL input line may be typed in any order. The 
line may even be typed backwards by using the appropriate space and 
backspace characters. Regardless of how the line is entered, it is 
evaluated exactly as it appears on the terminal before the user presses 
the RETURN key; the order in which statement components are entered is 
not significant. If there are too many characters in the line, APL 
will display the following message: 


LINE TOO LONG 
The entire line will be ignored. 


If the user has left spaces in the APL line, he may backspace to insert 
characters before he presses the RETURN key. Note that backspacing is 
a method for positioning the carriage; it does not cause characters to 
be erased or deleted. 


The user may discover that he has mistyped one or more characters in 
an APL statement before he presses the RETURN key and causes that 
statement to be transmitted. Errors may be corrected by means of the 
special keyboard characters described below. If a new line is entered 
by the user immediately after a CTRL/C, CTRL/U, or RUBOUT character 
has been processed, the line will not be indented six spaces in the 
normal APL fashion, but will begin at the left margin. 


Character Meaning 


RETURN Terminates the input line and causes the 
APL statement to be transmitted. 


CTRL/C Interrupts APL function execution, ex- 
pression evaluation, input, and output. 
Echoes +C on the terminal. 


In RT-1l1, returns control to command 
level; two CTRL/C characters must be 
entered if APL is performing input or 
output. 


In RSX-11M and IAS interrupts, 

APL execution but does not return 
control. On an APL terminal, echoes 
as 2n. 


1-13 
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Character Meaning 
Deletes the current input line and 
echoes tU on the terminal. Does not 
delete characters past the first 
carriage return/line feed combination 
encountered to the left of the CTRL/U. 


CTRL/U 


CTRL/U cannot be used to delete a 
multiple-line literal (see the 
description of the overstruck OU below). 


On an APL terminal, echoes as 2%. 


RUBOUT Deletes the last character from the 
current line and echoes the character 
on most terminals. 


Each succeeding RUBOUT typed by the 
user deletes and echoes another 
character up to the first carriage 
return/line feed combination en- 
countered to the left of the RUBOUT. 


The DELETE key is used in place of 
RUBOUT on some APL terminals. 


0 (overstruck QU) Causes an escape from an input loop or 
expression. Entered as mnemonic .OU 
on ASCII terminals. 


The OU sequence may be used to escape 
from a loop containing a quad or quote- 
quad input request. 


It may also be used to delete a 
multiple-line literal, which has 
been created by placing an odd number 
of quotes (usually one) on a line. 
When this occurs, subsequent lines 
are considered part of the literal 
until another line with an odd number 
of quotes is typed - for example: 

A®' THIS 
IS @ MULT IFLE 
LIWE LITERAL. ! 

a 
THIS 
IS @ MULTIPLE 
LIME LITERAL 


LE APL does not respond to an input 
line, the problem may be that the user 
has accidentally entered a multiple- 
line literal. To escape, the user 
should type a single quote on a line 
to terminate the literal or should use 
the OU sequence to cancel the literal. 
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Character Meaning 


CTRL/R Retypes the current input line. This is 
often helpful in cases in which exten- 
sive editing has been performed on a 
line. CTRL/R does not alter the input 
line and may be used any number of times. 


On an APL terminal, echoes as 2 


The example included below illustrates the use of many of the special 
immediate-mode editing characters described above. 


Ae Gry 
Pg. 1 oe a be 4 whe foe ode 4 oped ff t at 


a) 
= 2Q 


1.6.2 Processing Character Errors 

If the user transmits a line containing an invalid character - for 

example, an illegal overstrike in APZ mode or an illegal mnemonic 

in ASCII mode - APL generates the following error message: 
CHARACTER ERROR 


The line in which the error occurred is ignored, and APL indents to 
allow the user to retype it. 


CHAPTER 2 


THE APL LANGUAGE 


This chapter describes an implementation of the APZ language and pro- 
vides a detailed discussion of the features supported by APL-11. 


2.1 OVERVIEW OF APL STATEMENTS 


This section introduces the syntax rules that govern the construction 
of statements in the APL language. It summarizes statement components 
and discusses the types of APL statements and the evaluation of APL ex- 
pressions. 


2.1.1 Statement Execution Modes 
APL statements may be executed in either of two modes: 


e Immediate mode, in which statements and expressions 
are executed immediately, as entered by the user. 


® Function-definition mode, in which the user may con- 
struct a program or function consisting of APL state- 
ments, may name and save the function, and may exe- 
cute the function at a future time. 


The syntax of the language itself is identical in both modes; however, 

a few special symbols have been defined for ease of editing in function- 
definition mode, and these are not generally relevant to immediate-mode 
execution. Most of the examples in this chapter illustrate immediate- 
mode execution of individual APL statements. Chapter 3 describes the 
preparation and editing of programs in function-definition mode and 
introduces the special APL symbols used in that mode. 


In immediate mode interactions, APL clearly differentiates between sys- 
tem and user entries. When the user begins an APL session, the carriage 
automatically indents six spaces before allowing any text to be en- 
tered. The user enters a statement and presses the carriage return to 
indicate that the entry is complete. APL processes the statement and 
displays the result at the left margin of the next line. The system 
then begins a new line and automatically indents the customary six 
Spaces before unlocking the keyboard for the user's next statement. 
System and user entries can thus be distinguished, as shown in the fol- 
lowing interaction. 


2-1 
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System User 


AeD+3 
a 
is 
241 
3 
B+ 
8 
Aa-% 
2 
AGCAET 
ia) 
19 


2.1.2 Statement Components 
An APL statement may consist of the following components: 


® identifiers (variables, label names, user-defined func- 
tion names) 


e constants 
® symbols for APL primitive functions 


The following subsections summarize the characteristics of APL identi- 
fiers, constants, and data structures. APL primitive functions and 
operators are described in Sections 2.6 through 2.8. Labels and user- 
defined functions are discussed in Chapter 3. 


2.1.2.1 Identifiers - APL identifiers are used to name variables, user- 
defined functions, and labels within functions. An identifier may con- 
sist of any number of letters or digits; the first character of the 
sequence must be a letter, where a letter is defined as any character 
A-Z, A-Z, A or A. Only the first 31 characters of an identifier are 
significant, and embedded spaces are not allowed. 


A variable must be assigned a value before it can be referenced, or a 
VALUE ERROR results. A discussion of specific types of APL variables 
and detailed information about function and label name construction 
are included in Chapter 3. 


All APL tdentifiers are stored in the symbol table. The symbol table 
consists of 508 bytes in the clear workspace, and it expands dynam- 
ically, as needed, to the capacity of the workspace. Each identifier 
entry requires seven bytes, plus one byte for each character of the 


identifier, plus an optional fill byte, to bring the total to an even 
number of bytes. 


2.1.2.2 Numeric Constants - Numeric constants are of two types: deci- 
mal and exponential. The decimal form may be entered with or without 

a decimal point. The exponential form consists of an integer or deci- 
mal quantity, followed by F and the power of ten by which the quantity 
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is to be multiplied. All of the following numeric constants are valid 
representations of the same value. 


hoon 
ch af 


. 


eka tn) 
a 


36 9 60E71 S.54E2 SS400E™2 
356 556 356 6 6 


* 
= 
wb 


i 


7 


Ci 


When APL outputs a sequence of numeric constants, the system attempts 
to display the entire list in decimal form, as shown in the example 
above. 


In APL, negative numbers are represented by a numeric constant, immedi- 
ately preceded by a negative sign (). This sign is a distinct symbol 
(upper-case 2) and can be used only in negative numeric constants; it 

is not the same character as the minus sign (-) used to indicate a nega- 
tive or minus function. On ASCII terminals, the negative sign is typed 
as .NG,. Note that a space may not be included between the negative 

sign ( or .NG) and the number. It is displayed as the minus sign (-) 
on ASCII terminals, except in displays of user functions. Examples of 
using negative numbers and negative and minus functions are included 
below. 


ee 
ong 

2-3 
“e 

“2-"3 
t 

“BETS-" QE" 4 
“BEG 


2.1.2.3 Data Structures - Numeric and character data can be structured 
beh variety of ways. The following data structures are supported by 

e scalars 

® vectors 

@ matrices 

[) arrays of three or more dimensions 
A scalar is a single numeric or character value. A numeric scalar is 


entered as shown in the first example below. Note in the second example 
that a character scalar must be enclosed in single quotes. 


Be ' ct 


A vector is a 1l-dimensional array or string consisting of any number 
ef values. A numeric vector is entered as a list of values separated 


by at least one space - for example: 


ae1 23 4 
& 
1234 
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elements are i, 24 3, and 4, stored 


; i xr whose . 
Here 4 is defined as a vecto Several other numeric vectors 


in the order in which they were entered. 
are created below. 


%~ 2g 
“43% 

~1 23 
a “eZ 


Note that the first example generates a vector whose first element is 
“4; the second example applies the monadic negative operator (-) to the 


positive numeric vector 1 2 3. 


A character or literal vector is entered as a string of character con- 
stants enclosed in single quotes; no spaces are inserted between en- 
tries in a character vector, because the space character is itself a 
legitimate literal value. An example of entering and examining a char- 
acter vector is shown below. 


At ARCYMEFGOHT UKLMHOF QRS TUVWH Ts ! 
a 
ALOCKMEF GHT JKL MHOPQES TUYWEOTS 


A single quote character may be represented in a character vector by 
means of two consecutive single quotes - for example: 


HAME€ ' MAF THA! 1S ! 
RAMEE 
MAR THA ! S 


Several lines of character data may be entered as one literal string, 
as shown below. 


He THEE FS 
MUL. TIPLE Ln 
1. THRRAL. 
a 
THIS © A 
MULTI ROE L. ne 
LT TE FEAL. 


A matrix is a 2-dimensional array consisting of rows and columns. The 
user must enter values corresponding to each element of an array, but 
must also specify the shape of the array. The shape of an array is 
the number of dimensions which it has and the length of each of these 
dimensions. For example, a matrix may have six elements arranged as 
two rows and three columns, or three rows and two columns, as illus- 
trated by arrays A and B below. 


A 


3 
4 


> 
uhh 


CAGE 
OD db Fo 


The primitive rho (p) function is used to specify the shape of a new 
array, to reshape an existing array, or to determine the shape of an 
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existing array; it is described in detail in Sections 2.7.3 and 2.7.4. 
Following is an example of creating a simple matrix with the rho 
function. 


fe4 2FO 123 45 4 7 
4 


Rd 
NOP Ob 


Arrays of three dimenstons and more are also supported by APL. An 
APL array may have as many as 16 dimensions; the only restriction is 
that the size of the array must not exceed the size of the user's 
workspace. When an array of more than two dimensions is displayed, a 
blank line is inserted between each dimension, as in the following 
example. 
2.9 9 4p  ABCHEFGHISKLMNOF QRS TUVWHTZARCIEF | 
ABC 
EF GH 


TK LL. 
MROF 


QRS T 
UV Bs 


VR AK 
COR 


2.1.3 Significance of Spaces and Comments 


Spaces are usually not significant in APL. They need not be included 
to separate primitive functions from constants or variables but they 
may be used in such statements if desired. In particular, on ASCII 
terminals the mnemonics for APL primitive functions need not be either 
preceded or followed by a space. The following pairs of expressions 
are equivalent. 


AE Et ge J 
Ae Fy fF - 


«TRE 
«TR BE 


Spaces are also not required between a succession of primitive func- 
tions - for example: 


Ae /E 


Spaces must be included to separate the names of adjacent user-defined 
functions, constants, and variables. For example, they are required 
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when entering a series of numeric constants as a vector. The spaces 


included in the following statements are necessary. 


y TRIG 3 
Re 4 5 
xeF 12 
Spaces may not be included between a negative sign ( or .NG) anda 
numeric constant (Section 2.1.2.2). 


Comments may be used freely in APL. Their use is particularly relevant 
in function-definition mode. Comments must appear on separate lines 
and may not be included on lines containing APL statements. The first 
character in a comment line must be a lamp (a) character, formed by 
overstriking the down union (n) and jot (°) characters. If an ASC11 
terminal is being used, the first character in a comment line must be 

a double-quote ("). Chapter 3 describes comment lines in greater 
detail (see Section 3.2.4) and illustrates their use in a variety of 
user~defined functions. 


2.1.4 APL Statement Types 

There are two general types of APL statements. 
@ branch statements 
e assignment statements 


Branch statements are used to restart a function and to transfer con- 
trol from one part of a program to another. These statements are most 
relevant in the context of user-defined functions and are described in 
Chapter 3. 


Assignment statements are used to assign one or more values to a vari- 
able or data structure. The general form of an assignment statement 
is illustrated in the following example: 


He 245 


where the constant 3 is added to the constant 2 and the resulting 
value, 5, assigned to variable A. There may be multiple assignments 
or specifications in a single APL statement - for example: 


EZ Ee Able? 


Here the value 7 is assigned to C, 11 to B, and 14 to A. The expres- 
sion is evaluated according to the rule described in Section 2.1.5. 


Multiple specifications are particularly useful in initializing data 
values, as illustrated below: 


AGCKECELED 


The expression: 


2+ 
5 


may also be considered an assignment statement; in this case, no ex- 
plicit variable is available to receive the result, so the value of 
the computation is simply assigned to the terminal. 
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The result of an APL expression is displayed at the terminal, unless 
the leftmost operation on the line is an assignment or branch opera- 
tion or unless the user is in function-definition mode. 


2.1.5 Evaluation of APL Statements and Expressions 


Unlike some languages, which perform multiplication and division before 
addition and subtraction, APL has no explicit operator precedence. APL 
statements and expressions are evaluated in strict right-to-left order, 
regardless of the particular functions in the statement. For example, 

the expression: 


BXAtS 
27 


evaluates to 27, using right-to-left evaluation, rather than 17, which 
would be the result if operator precedence were employed. All APL 
statements are executed as if they were parenthesized from right-to- 
left. Thus, the expression: 


3x44 
27 


is interpreted as: 


3X C4+5) 
27 


The user may control the order in which the individual operations in a 
Statement are evaluated by explicitly parenthesizing the operations to 
be treated as a quantity. To cause the expression included above to 
evaluate to 17, not 27, the user enters the following: 


(3X4) 45 
17 


This expression evaluates to 17, because 5 is added to the quantity 
3x4, not simply to 4. 


2.2 FORMATTING APL NUMERIC OUTPUT 


The APL-11 system may be configured as either a single-precision or a 
double-precision system for the internal representation of floating- 
point numbers. The single-precision version of APL-11 uses a precision 
of about seven decimal digits; the double-precision version uses a 
precision of about 16 digits. 


The internal precision of numeric representation in APL is not subject 
to the user's run-time control. However, the user may specify both the 
desired precision of numbers to be displayed as output and the maximum 
length of the output line. The )DIGITS system command (Section 5.4.2) 
sets the output precision, and the )WIDTH system command (Section 5.4.3) 
sets the length of the line. The examples in this section illustrate the 
impact of both of these commands on the appearance of APL output. Vector 
and scalars are printed in a compact form; arrays and higher dimensional 
structures, however, are formatted for tabular output. 


Before a numeric array is printed, it is scanned to determine the "best" 
output format. The columns of numeric arrays are aligned and packed to- 
gether with at least one space of separation. Once the maximum field 
width has been determined for an array, the numbers are left-justified 
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in that field. No attempt is made to align the decimal points. APL 
attempts to display all numbers without decimal points and exponents. 
When scalars, vectors, and arrays are being displayed, only those 
numbers that require exponentation are displayed in that form - for 


example: 


S46 S356.0 S546EO 5.546 Y 
556 556 S54 S.56E79 


Fractional numbers are displayed with a leading zero before the decimal 
point. Note that the maximum number of displayed digits has been set 


to six in the examples below. 


JEEGITS 6 
was ? 
1000000000 
LE 
Le" 2 
0.01 
“0000000001 
“Yen 1G 
16 23485 
123400 
2 Sri 
a oe ae | 
fh 2 4 
2 Bf 6123 “.123 «123 «123 .123 
1,2300E71 “1,2300871 1.230081 
1.2300E"1 1,2300871 =§, 43218710 
@ 3P.123 3 6123 .123 128456 1e4 
6.1230 3 0.1230 
0.1230 123454 10000 





me 48 





When the length of a vector or array exceeds the maximum line width 
specified in the )WIDTH command, the excess numbers are indented 
beneath the second element of the first line, as shown below. 


FULT eG (generate 30 consecutive numbers) 
WAS 7D 
40 
12345 678 9 10 11 12 

13 14 45 16 17 18 19 

20 21 22 23 24 25 26 


27 28 29 30 


@r lo (compute natural logarithms) 
O 0.69315 1.09861 1.38629 

1460944 1.79176 

1.94591 2.07944 

woh P2722 2.30259 


JORGLTS 2 
WAS & 
®1190 
O 60,69 1.4 1.30 1.41 1.79 
1.95 23.08 2.2 23.3 
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In APL there are actually two ways to control the numb igi i 
er of digits dis- 
played in numeric output. The )DIGITS system command sets the Subcat 
precision directly, and the floor (L) function, illustrated in the last 
example below, rounds the numbers included in the function. In this 


example, the numbers are rounded to three lace i 
cecioen! eolne. p s to the right of the 


JUEGITS 6 
WAS % 
JWIETH 72 
WAS 30 
1S 
O 0.69315 1.09861 1.38629 1.40944 
LEWSxXL Ste seers 
0 0.693 1.099 1.386 1.609 


2.3 ERROR HANDLING 


When an error is encountered in an APL statement, an error message is 
normally output, followed by a display of the line in which the error 
occurred. An up-arrow (t) beneath this line identifies the particular 
point at which the error was discovered. Examples of several common 
error conditions are included below. 


He 
& X Fx 


VALUE ERROR: 
AXE 
+ 

L+1B+243 


SYMTAX ERROR 
LF1B+D+3 
t 
1241234567 


LEMGTH ERROR 
1 2ti 2345 67 
~ 


Because APL is a highly interactive system, the user can almost always 
respond to an error condition simply by correcting the statement in 
which the error occurred. This characteristic of the language also 
facilitates a trial-and-error approach to program development. 


In immediate mode, the user generally responds to an error message by 
reentering a corrected statement or by changing the value of a variable 
used in a computation. In function-execution mode, APL outputs an 
error message, along with the name of the function and the line number 
of the statement at which the error occurred; it also suspends execu- 
tion of the function. The user may then terminate the suspended pro- 
gram, restart it at another statement, or perform debugging operations 
before resuming execution. These operations might include editing the 
suspended program, displaying the current values of variables used in 
the program, examining the status of functions called by the program, 
or developing a test program to analyze the output of the suspended 
program. Chapter 3 describes techniques for developing and executing 
functions. 


If certain types of errors occur in function-execution mode, the user 
May not want execution of the function to halt to await correction of 
the error conditions. The implementation of APL described in this 
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handle error conditions under 


manual therefore allows the user to n 4.3.2) and the execute («) 


program control by I-beam 16 (Sectio 
operator (Section 2.7.21). 


2.4 ARRAY INDEXING AND COMPARISONS 


This section introduces the use of array indexing in APL and fh ae 
background information on the function of the index origin se oy 
in performing comparisons. These concepts are helpful in un pon a 
ing the examples included in subsequent sections of this chapter. 


2.4.1 Indexing Arrays in APL 


The concept of using and entering values for arrays in APL has already 

been introduced in this chapter. An element of an array may be indexed 
by specifying a bracketed element number to the right of the array name 
as follows: 


YL 
This expression represents the simplest form of indexing and can be 


used to access the first element of vector V. If V consists of the 
vector shown below, then Y[3] is 7. 


Vex 4 7 9 
vega 
7 


In the examples shown above, the array being indexed is a vector, and 
the index is a scalar value representing the position of the desired 
element in the vector. A more complex form of indexing occurs when 
the array is of higher dimension or when the index is itself an array. 
The latter case is illustrated below. 


te? 4 § 
VelO 22 31 49 56 68 72 
Von 

22 49 56 


Here VY and I are both vectors. The expression V[ZI] is used to access 
the elements of VY referenced by I ~ the second, fourth, and fifth mem- 
bers of vector V. The result of V[I] is itself a vector consisting of 
the same number of elements as vector I. JI may be a matrix ora higher- 
dimensional array; the result always has the same shape as I. 


The array being indexed need not be a variable. It may be a constant 
set of values or even an expression to be evaluated, as shown below: 


765 43 2 12 47 
& 4 

(248 416 * 201 22 
4 16 


In general, there must be as many indices as there are dimensions in 
the array. In APL, the number of dimensions is known as the rank. 
For a vector, a single index is sufficient to identify the desired 
element. A matrix or 2-dimensional array requires two indices, sep- 
arated by semicolons; a 3-dimensional array requires three. Thus, if 
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M is of rank N, then M must have W subscripts, separated by semi- 
colons. If Mis a matrix, then M[2;4] is the element at the inter- 
section of the second row and the fourth column of M; the first 
element in brackets identifies the row and the second specifies the 
column. The shape of the result of M[Z;J] is (pI),pJ7 - for example: 


A subscript may be omitted from an index specification, but the semi- 
colon must be included if only one matrix dimension specification is 
being omitted. If the right subscript is omitted, then all columns 
are selected from the matrix; if the left subscript is omitted, then 
all rows are selected - for example: 


ro) 


1 2 3 4 

8 & 7 8 

9 10 dil d2 
Ae 3 

1 2 3 4 
alge 31 

2 3 

& 7 

10 da 


Note that the semicolon is required to indicate which subscript has 
been omitted. If the index specifications are completely omitted, as 
in the first example below, the entire array is displayed. In the 
second example, the entire array is displayed because one semicolon - 
one fewer than the number of dimensions in the array - is included. 


Ree BPI 2 8 4 
se 
3 4 
BE eo 
L 2 
3 4 


Some additional examples are included below: 


Ve hABCTHEF | 
VCS 3 





cE 

Vl6 3 4 3 2 1a 
FEDCEA 

Me2 Sr2 5 4 6 5 4 
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¥tMI 

REL 

FED 
Me? 2F1 2 2 od 
eM M sh) 


cy 


fom) 
ae ites ae? 
Wi ee ee 
arg eae 


Indexing may also be used to change specified elements of an array by 
replacing their values with new values. An example of this is shown 
below. 


a 

i 2 2 

4 5 6 
OC1¢2 B1e7 8 
AL2Q¢1 BI1e9 
a 

1 7 8 

9 9 & 
ALL 1I1e12 
a 

12 7 8 

9 9 & 


2.4.2 The Index Origin 


The index origin specifies the index of the first element in an array. 
If the index origin is 1, then members of vector V are numbered V[1], 
Vfi2], and so on. If the index origin is 0, elements begin at Y[0], not 
V[i]. The default index origin setting in the clear workspace is l, 
but the user may change this setting to 0 or reset it to 1 by means of 
the DIO system variable (Section 4.2.2) or the JORIGIN system command 
(Section 5.4.1). The index origin setting is saved with the rest of 
the workspace. 














The value of the index origin is also used by APL in many of the func- 
tions described in Chapter 2. These include: 


e catenation (,) 


e lamination (,) 
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e compression (/) 

e expansion (\) 

e dyadic transpose (&) 
e reverse (6) 

e rotation (9) 


®e grade up (A) 
e grade down (f) 
e roll (?) 


e deal (?) 


® reduction (f/) 
e scan (f\) 
r index generator (1) 
e index of (1) 
HrOe] 
Me 1 4 
be 
L234 
Hy 3 
3 
AP So 
3 
yea 
43 2 14 
Py, 
a 
SPS 
123 45 
PORTE Lt O 
was | 
Ae 4 
a3 
O12 3 
ays 
3 
Lo ae | 
3 
ya 
32 10 
FL 
0 
OPS 
403 12 


2.4.3 Comparison Tolerance or Fuzz 
When two very large numbers, or two numbers that have non-zero frac- 


tional components are compared in the APL-11 System, they are con- 
sidered to be equal if they are within a certain comparison tolerance 
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of "fuzz" quantity of each other. Comparison tolerance is used in the 
following APL functions: 


e relational operators (<,<,=.2,>.%) 
e index function (dyadic 1) 

e membership function (dyadic e«) 

® floor (L) 

e ceiling (f) 


The amount of tolerance applied by APL-11 may be controlled by the 
user by means of the [CT system variable (Section 4.2.1) or the 
)FUZZ system command (Section 5.4.4). The default relative Fuzz in 
the clear workspace is set to 5E 7 in single-precision systems and 
5E 15 in double~precision systems. The Fuzz setup is saved with the 
workspace. 





The comparison tolerance is OCT times the larger of the two numbers 
that are being compared, in absolute value. The formal definition 
for tolerant equality is the following: 


R+(|A-B)sO0rx(|A)F 1B 
Examples of user control over comparison tolerance are included below. 


{JO Te peony 

'OL' Cltdeted+10x- 1257) 
OOOOOOOOLLALLLAL LEA 24 4144 

ETE LE" 42 

‘OL! Lithea] 
OOOOOOOOOOOOLALLIL14 44411 


2.5 INPUT/OUTPUT OPERATIONS 


The implementation of APL described in this manual facilitates input 
and output operations on a variety of system devices. Chapter 6 de~ 
scribes the file system used to handle file-oriented I/O in ASCII 
sequential and random-access format. This section is oriented to ter- 
minal input and output, but most of the general information described 
here is applicable to all system I/O devices. 


In APL, input and output operations are generally expressed by means 

of the special quad operator, (1. Input/output statements are special 
kinds of assignment statements. If a quad symbol appears immediately 
to the left of a left-arrow, the value of the expression to the right 
of that specification arrow is output - for example: 





Se 15-MeS+4 
? 
Here the quantity 3+4 is assigned to the quad operator and displayed. 
The value of X iS computed but not displayed. Terminal output can also 


be accomplished simply by entering the name of the variable whose value 
is to be displayed: 


4 
K 


2-14 


THE APL LANGUAGE 


If a quad symbol appears anywhere in an APL statement except immediate- 
ly to the left of a left-arrow, input is accepted from the terminal, as 
in the following: 


Ae Bx+S 
fl; 
? 


Table 2-1 lists the formats of the input and output operations that 
can be performed in APL-11, along with section references. 


Table 2-1 
Input/Output Operators 


A+O Quad (evaluated) input 

A<f Quote-quad (character) input 
A«M Quad-del (unedited) input 
A+CeltypelN File input 

A Normal output 

A3B3C Heterogeneous output 

O«A Quad output 


M<A Bare output 


CAL type lA File output 





The file input and output functions are described in detail in Chap- 
ter 6; the basic forms of the quad operator are discussed below. 


2.5.1 Quad Input Mode 


The most basic form of APL input is called evaluated input. Evaluated 
input means that the expression entered by the user is evaluated for a 
value, which then replaces the 0 character. In the following example, 
the value entered by the user is assigned to the variable to the left 
of the specification arrow. 

Ke[] 

3 

18 
The K variable takes on the value (18) entered by the user at the 
terminal. 


APL prompts the user to supply a value by displaying a quad character 
followed by a colon, as shown below. 
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ee BS KTAS 
ns The user requests evaluated input. 


a APL prompts and the user enters a 

BG string which again requests evaluated 
Sxe8 input. 

We APL prompts again and the user enters 3. 
Léxtle2 

3 The second input string evaluates to 
3 16x3-2 or 16, and the first evaluates 

& to 3x16+8=6; APL responds with 6. 


To enter a character string as a value in quad mode, the user must 
enclose the string in single quotes - for example: 


MC EL] 
TROT REMCUGM Chor 


MiB ia 
HOT EHOGUGH CORE 





If the user enters only a carriage return or spaces followed by a 
carriage return, APL again displays the prompt and waits for the input 
to be reentered. While the system is awaiting input, the user may 

enter and execute a system command or may define a function. The input 
request remains pending. After the desired operation has been per- 
formed or the user has returned to immediate mode, APL prompts again 

and waits for input. If an error is encountered in the input, APL dis- 
plays the appropriate message and allows the user to reenter the input 
but does not reprompt. To reenter the input, the user must first type 
+0, which will cause the prompt to appear; he may then reenter the input. 


2.5.2 Quote-Quad Input Mode 


A version of the quad operator called the quote-quad operator (ff) is 
used especially for the input of character data. An example of quote- 
quad mode is shown below. 


Hef} 
THAT'S AMAZING 


THATISG AMAZING 


Unlike evaluated input, quote-quad input allows character strings to 
be entered without explicit quote characters. When APL encounters a 

M symbol, it positions the carriage at the left margin and accepts the 
data entered by the user up to the next carriage return as a character 
string. If a single character is entered, APL treats it as a literal 
scalar; a string is stored as a literal vector. If the user enters 
only a carriage return, APL treats this input as a vector of length 

O: this is Significantly different from the handling of empty input 

in evaluated input mode, in which APL rejects the input and waits for 
the user to reenter it. 
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Quote-quad input is also called unevaluated input. If the user enters 
an expression, APL does not evaluate it, but simply treats it as a 
character string. APL does edit the characters that are entered; for 
example, overstrikes which are made up of three separate characters 
are combined into a single character. 


2.5.3 Quad-Del Input Mode 


A special version of the quad operator, the quad-del operator (M) 
enters characters exactly as typed by the user. No special editing of 
APL characters is performed. The backspace, for example, is treated 
aS a special character, and an overstrike symbol is not created. The 
following statements illustrate the difference between quad-del and 
quote-quad modes in entering overstruck APL characters. 


Hey 
Ha 

Fr Me 
4 

well 
ya 

PH 
2 

io { & rn 


"y 


The example included below shows the particular use of quad-del mode 
in accepting input from ASCII-mode terminals. Mnemonics entered in 
ASCII mode are not decoded. 


A. Qo 
+ TRE 

“kO A 
4 

AQ. 6 AG 
+TRA 

7RO A 


oRO 2 TRAC 


As in quote-quad input mode, if the user enters only a carriage return, 
APL treats this input as a null vector of length zero. 


2.5.4 Escaping from an Input Loop 


If an input request occurs within an infinite loop in an APL defined 
function, the user can interrupt function execution by typing OV, as 
follows: 


O< baeckspace>vU 
thus overstriking the two characters. Users of ASCII terminals 
escape by typing the .OU mnemonic. An escape of this kind causes 


function execution to be interrupted but does not cause an exit from 
the function. 
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2.5.5 Normal and Quad Output Modes 


If a quad operator (4) appears immediately to the left of a left-arrow, 
the value of the expression to the right of the arrow is output. 
Because APL automatically displays the value of an expression or 
variable not explicitly assigned to another variable, it is often not 
necessary to express explicit terminal output requests. For example, 
the APL statement: 


fee 
3 


is equivalent to the statement: 


& 
3 


because both have the effect of displaying the value of 8B. 


Quad output mode is especially helpful when an APL statement con- 
sists of multiple specifications ~ for example: 


Ae S+MleSx4 
20 


This statement performs the computation and displays the desired out- 
put - the result of the computation 5x4. It is more efficient than 
the following similar examples: 


Sx4 

20 
AG 3+20 
AERX4 
ry 

20 
AGZ+A 
ray 

23 


If the last operation (the leftmost operation) being performed in a 
line is an assignment (+) or branch (+) (see Section 3.4.1), then no 
final output is produced. The following APL statement will not cause 
output to be displayed: 


AGLSX4 


but the example shown below will display a value: 


A+O65 


2.5.6 Heterogeneous Output Mode 


APL users often need to mix character and numeric data on the same 
output line. Mixed output lines of this kind are called heterogeneous 
output. The APL user requests heterogeneous output simply by entering 
a series of values or expressions, separated by semicolons, in the 
order in which they are to appear. The values may be parenthesized. 
The following is an example of the use of heterogeneous output. 
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As mentioned in Section 2.5.5, a value will not be displayed if the 
leftmost expression on a line is an assignment or branch operation. 


The heterogeneous output facility may be useful for entering function 
lines that consist of multiple APL statements. The user should 
remember, however, that APL evaluates expressions in right-to-left 
order by line, without regard to embedded separating semicolons. 


2.5.7 Bare Output Mode 


Bare output is a special kind of APZ output that is normally accom- 
plished by means of the quote-quad character - for example: 


M<'SPECIFY USER ID' 


The normal output described in Section 2.5.5 is terminated by a car- 
riage return/line feed pair so that the next input or output begins 
at a standard position on the following line. Bare output, on the 
other hand, is not concluded by a carriage return/line feed if it is 
followed by another bare output request or by quote-quad input. The 
character input accepted after a bare output operation is handled as 
if the user had spaced over to the position immediately following the 
final character of the bare output value. This implies that the 
resulting value of the input string normally contains a number of 
blanks, as shown in the example below. The use of bare output allows 
a character response to appear on the same line as the output text. 


ghey 
Cl] fetarke rou REArY TO EMTER VALUES? | 
2] Gen 
ca] 


Lien y 
QE TOU REO OY TO ERMTER VALUE P HO 


ey 
no 


Carriage returns that would normally be inserted because of a limita- 
tion on page width are not included in bare output. 


If bare output is specified in immediate rather than function-execu- 
tion mode, it is usually not distinguishable from normal output. A 
bare output statement such as [J+A must be followed by an input entry 
at the terminal, and thus the output will be concluded by the conven- 
tional carriage return. Bare output is therefore more appropriately 
utilized in function-execution mode. 


2.5.8 Terminating Output 
The display of output on the terminal may be terminated before it has 


been completed by pressing the CTRL/O or CTRL/C key. See the dis- 
cussion in Sections 1.5.1 and 1.5.2. 
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2.6 PRIMITIVE SCALAR FUNCTIONS 


APL primitive functions are of two types: scalar and mixed. Scalar 
functions have the following characteristics: 


6 They take single-number (scalar) arguments 
@ They yield scalar results 
® They are used primarily for basic arithmetic and logical 


operations, such as addition, exponentiation, maximum value, 
and logical OR 


With a few exceptions, the primitive scalar functions take numeric 
scalar arguments. Only the relational functions (<,<,=,>,2,#) take 
either character or numeric arguments. 


The logical functions (v,A,¥*,x,~) must have arguments that are equal 
to 0 or l. 


Table 2-2 summarizes the primitive scalar functions available in this 
implementation of APL, and provides a definition or example of each. 

Most of the functions are straightforward and familiar arithmetic or 

logical functions and do not require detailed discussion. 


The following subsections describe the difference between monadic and 
dyadic primitives, discuss the extension of scalar functions to 
arrays, describe the use of APL operators with primitive functions, 
and summarize any information about the functions in Table 2-2 that 
is either not obvious or different from the ordinary mathematical 
interpretation of the functions. The monadic roll (?) primitive is 

a scalar function and is included in the table for completeness; how- 
ever, it is the only primitive scalar function that is origin- 
dependent (Section 2.4.2) and is more appropriately described in con- 
junction with the dyadic deal function in Sections 2.7.21 and 2.7.22. 


2.6.1 Monadic and Dyadic Functions 


Most of the primitive scalar functions and some of the mixed functions 
described in Section 2.7 have been implemented in two forms: monadic 
and dyadic. WMonadite funetions take only a right argument - for 
example, +A (reciprocal), !B8 (factorial) or ~1 (logical NOT). 

Dyadte funettons take both left and right arguments - for example, 

3+2 (addition), A[B (maximum), and x=Y (equal). The operator is 
always a single APL symbol, usually the same as the corresponding 
symbol used in ordinary mathematics. 


The syntax of a function (i.e., the presence of one or two arguments) 
determines whether the function is monadic or dyadic. For example, 
|4 is a monadic function used to determine the magnitude or absolute 


value of the argument A. AjB is a dyadic function used to obtain the 
residue or remainder available after dividing B by A. The particular 
function specifed by the | symbol is dependent upon the context of 


the statement. 
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Table 2-2 
Primitive Scalar Functions 


Monadic Form fY Symbol Dyadic Form XfY 
Definition Definition 
or Example Function Function or Example 


+Y¥<o0+Y Plus + Plus 5.344.239 .5 


















-Y+70-Y Negative Minus 5-6<> 1 










xY<«>(Y>0)-Y<0 Signum Times 4x7, 2+«+28.8 








Reciprocal Divide 





+¥<oieY 





*Y<+ (@22.71828,..) *7 








Exponential Power 













5 | 7+«33 





Residue 





“6.7<36.7 





Magnitude 









Ceiling Maximum 





Floor Minimum 

















Natural 
Logarithm 


X@Y++Log Y Base X 
X@Y<>+(@Y)+@X 






@ «N+3N<> «ON Logarithm 















XtYeo( 2 Y)eC1X)x 1 Y-X 
al Geode 216<«+15 


Binomial 
Coefficient 


Factorial 






10451 '¥*«oYxiyY-4 
or !Y++Gamma(Y+1) 









Roll 





?Y<«+Random choice 
from iY 















Pi times 





Oy¥<>(3.14159...)xyY Circular See Table 2-3 








~1<30 Not 


~0<31 









And 
Or 

Nand 
Nor 





























< Less Relationals: 
< Not greater Result is 1 if the 
Equal relation holds and 






2 Not less 0 if it does not. 
> Greater 3>7+30 
z Not equal "A'S'Clesd 
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Table 2-3 
Dyadic Circle Functions 





(1-Yx2)*.5 (1-Y¥x2)*.5 








Arcsin Y Sine Y 
Arccos Y Cosine Y 
Arctan Y Tangent Y 









(14+¥*2)%*.5 






(“1+Y*2)%*.5 


Sinh Y 





Arcsinh Y 





Cosh Y 





Arccosh Y 








Tanh Y 





Arctanh Y 


2.6.2 Extending Scalar Functions to Arrays 


The primitive functions described in this section are considered 
scalar functions because they take scalar arguments and yield scalar 
results. The operations performed by these functions can, however, 
be extended to arrays. A primitive scalar function is applied to an 
array on an element-by-element basis. Thus, if the user specifies an 
addition function in which both arguments are vectors, the cor- 
responding elements of the vectors are added - for example: 


oS Gta 7 a 
Ld LS we 


The arrays on which the primitive scalar functions operate may be of 
any dimensions. If a dyadic function is being performed, the arrays 
specified as the arguments of the function must generally have the 
Same number of elements and be the same shape (e.g., a 2-by-3 array 
is not equivalent to a 3-by-2 array). There is one exception to this 
rule. If one argument is an array and the other is a scalar or a 
single-element array, the single value is applied to every element of 
the array. The following two examples are therefore equivalent. 


Oo o% S44 7 2 


12 12 7 


The following examples illustrate the use of several other primitive 
scalar functions. 
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ho 


Se3 BFS 6 8 S21 6 4 
a 


3 6 #8 

3 2 1 

& 4 2 
OKA 

25 34 64 

9 4 1 

36 16 4 
2xA 

10 12 #16 

& 4 2 

12 6 4 


2eO 123 485 67 8 
124816 32 64 128 256 

49 16 25 34e0.5 
2345 6 


2.6.3 Using Operators with Scalar Functions 


Operators are special APL functions that take dyadic primitive scalar 
functions as their arguments. For example, the reduction operator 
combines the elements of a vector or the elements along one dimension 
of an array. The elements are combined in accordance with the spec- 
ified function (e.g., addition, multiplication, etc.). The following 
example illustrates the addition of the elements of a vector. 


& 


The plus sign in this statement could be replaced by any of the dyadic 
primitive scalar functions in order to perform a different function. 


The formats of the four APL operators are listed below and are 
described in detail in Section 2.8. 


e reduction (f/) 

® scan (f\) 

e inner product (fg) 
® outer product (°°:f) 
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2.6.4 Relational Functions 


In APL, the relational functions (<, S$, =, >, 2, #) return results; 


i i i of the 
they are not simply comparison operators. An expression 
foo ASB yields a result value of 1 if the relation holds - for 


example: 


D> 4 


4rd 


i) 
roel y tel 


These functions may take either numeric or character arguments; how- 
ever, they may not have one numeric and one character argument, or a 
DOMAIN FRROR results. Note that = and # will return a 0 result for 
arguments of different types. For characters, the DAVY system variable 
defines the collating sequence to be used in relational functions. A 
character appearing earlier in DAV is "less than" one appearing later 
(Section 4.2.6). 








When used with boolean arguments (0 and 1), the relational functions 
may be used to perform logical operations. For example, the not 

equal (#) function performs an exclusive OR operation if its arguments 
are O's and l's. 


OQ 1 Oo 140 O 1 FL. 
oid 
2.6.5 |: Determining the Residue 


The dyadic residue (|) function is used to obtain the remainder or 
residue of a number. In the function: 


5|8 


where 5 and 8 are both positive, 3 is the remainder when 8 is divided 
by 5, and 3 is considered the 5 residue of 8. The residue is a unique 
number whose value is in the range between the value of the left 
argument and zero. 


The residue function, A|B, has the following characteristics: 


e If the left and right arguments are equal (A=8), the residue 
is 0. 


e If the left argument is zero (A=0), the residue is the value 
of B (4/8 = BY. 


e Te A is not zero (A4#0), the residue is in the range 4 through 
Oo; it may equal @ but not A. For some integer, I, the residue 
can be expressed as B-IxA. 
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Examples of these cases are included below. For a discussion of the 
outer product operator included below (Ac.|B), see Section 2.8.4. 


7\7 
0 
7\0 
0 
0|7 
7 
0| 7 
“7 
A+3 0 3 
B«-6 “5 4 °3°2°71 012 3 4 5 6 
Ao. |B 
0 L 2 08h 2Gda1l2 01 2 0 
“6 5 °4°3 7271 0 1 2 3 4 5 6 
0-271 O6°2 °1 @°2 "2 06°27) 6 
X*21.824 
-O1|X 
0.004 


The result of a residue function has the same sign as the left argu- 
ment of the function. If the left argument is negative, then the sign 
of the result is negative, as shown below. 


“> 5| 7 


because 2= 7+] °5 


The arguments of the residue function need not be integer numbers - for 
example: 


2|5.8 


1.2|3.9 
3 


The formal definition of the APZ-11 residue function is the following: 
A|B++B-AxLBtA+A=0 


where +> indicates that the two sides of the expression have the same 
value. 


2.7 PRIMITIVE MIXED FUNCTIONS 


The functions presented in this section are primitive mixed funettons. 
Primitive scalar functions take scalar arguments, yield scalar results, 
and are extended to arrays on an element-by-element basis. Mixed 
functions, on the other hand, may take array arguments and yield scalar 
or array results, or may take scalar arguments and yield array results. 


2.7.1 Summary of Primitive Mixed Functions 
Table 2-4 summarizes the primitive mixed functions available in this 


implementation of APL, along with the operators introduced in Section 
2.6.3 and described in Section 2.8. 


Table 2-4 
Primitive Mixed Functions and Operators 





Monadic Form fy 1 








92-¢ 


























Takes Dyadic Form XxfyY 
; Coordinate Origin- T 
Section Function Definition Argument Symbol Dependent Definition Function Section 
Mixed 
Functions: 
26158 Returns array shape py p no Reshapes an array 2.7.4 
23755 Generates consecu- Y 1 yes Finds an index 2.7.6 
tive integers 
2.7.7 Converts to a vector v¥ - no Catenates or laminates 22708 
/ no Compresses an array 2.7.9 
\ no Expands an array 2a Prado 
t no Takes array elements D -, Piecaled: 
+ no Drops array elements 2. Fak 
257313 Transposes an array ay g yes? Transposes an array 2.7.14 
614 Lo Reverses an array oY o no Rotates an array 2.7.16 
2h. LS Sorts in ascending AY 4 yes 
order 
ae ae Rs) Sorts in descending yy y yes 
order 
Qi LG Rolls random integers ?Y yes Deals random integers 20h +20 
Dis'T's 2A Constructs a charac- TY no Encodes a number in 2.7 B2 
ter string another base 
1 no Decodes a number Da Fo 23 
representation 
2.7.24 Executes a character cY € no Determines array 2/7225 
string membership 
Qe hw ee Eliminates duplicates u u no Determines union of 2. T4260 
in a set two sets 
a no Determines intersection 2.7028 
of two sets 
~ no Excludes elements in 2.7.29 
first set but not in 
second 
c no Determines a proper 2.7.30 
subset 
> no Determines a strict 2.7.31 
Superset 
S. no Determines a superset 2.7.31. 
co no Determines a subset 2.7.30. 
2.7232 Formats an array wy e no Formats a numeric array 2.7.33 
with width and precision 
2.7.34 Performs matrix Ey iB no Performs matrix division 
inversion 
Operators 
2.8.1 Reduces an array S/Y f/ no 
2's Bie2 Scans an array F\Y f\ no 
fg no Computes inner product 2.8.3 
og no Computes outer product 2.8.4 














tapply to both monadic and dyadic forms 
*pyadic form only 


3pyadic form, left argument only 
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The boxed information at the beginning of each section provides addi- 
tional summary information, which is repeated for quick reference in 
Appendix A (Table A-9). In these descriptions, "any" means that any 
argument domain (character or numeric) or argument shape (scalar, 
vector, or array) may be specified. If the argument domain is "any*", 
this indicates that arguments may be either character or numeric, but 
both arguments must be the same type. 


2.7.2 Specifying Array Coordinates 


When expressing mixed functions for arrays of two dimensions or more, 
it may be necessary to specify the particular array coordinate to 
which the function applies. This is done by including in the function 
a bracketed expression representing the desired coordinate in the 
specified array. For example, the following function catenates array 
A to dimension 1 of B. 


A,{1] B 


An array coordinate can be specified for the following functions and 
operators: 


Function Symbol Section 
catenation . Zedie 
lamination F 2.7.8 
compression / 2.7.9 
expansion \ 2.7.10 
reverse > 2 1S 
rotation co) 2.7.16 
sort (ascending) A 2.7.17 
sort (descending) y 2.7.18 
reduction £/ 2.8.1 
scan £\ 2.8.2 


The array coordinate is origin-dependent, that is, it depends upon the 
current value of the index origin. In the above example, A is 
catenated to the first dimension of B if the index origin is 1 and to 
the second dimension of B if the index origin is 0. 


If the bracketed expression is omitted from a mixed function, the func- 
tion is performed on the last coordinate of the array. If B is a 
4-dimensional array, the following function compresses along coordi- 
nate 4. 


A/B 
The user can specify that certain functions are to be performed on the 
first coordinate by using a special symbol, formed by overstriking the 


minus sign (-) with another symbol, usually the normal symbol of the 
function - for example: 


AB 
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All symbols are shown below. 


Function Symbol 
compression 7 
expansion \ 
reverse cS) 
rotation 9 
reduction ff 
scan fy 
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2.7.3 0: Returning the Shape of an Array 


Function: monadic rho (p); R<pY 
Argument Domain: 

left: - 

right: any 
Argument Shape: 


left: - 
right: any 
Result Range: null or non-negative integers 
Result Shape: vector; pk<*ppY 
Origin-Dependent? no 
Take Dimension Argument? [0° 





The monadic form of the rho (po) function returns the shape of an array. 
If B is a character vector consisting of 'ABCDEF', then the rho func- 
tion included below returns the number of characters in the array. 


Kz 
ABCKIEF 

PE 
4 


Because B is a 1l-dimensional array, pB returns only a single number. 
If A is a matrix with five rows and six columns, then the following 
result occurs. 


ra) 
i 2 e 4 pa é 
7 8 9 10 dit 12 
13.614 #«%iS 16 17 #18 
19 20 21 22 23 24 
2o 26 27 28 29 30 
FR 
ou. 4 


If the vector that is the argument of the function is a 1-dimensional 
array with a length of 1, then the rho of the array will be 1. The 
following example illustrates the generation and examination of an 
array consisting of the single digit, 3. 

Kees 

pK 

‘IL 

See Section 2.7.4 for a discussion of the dyadic form of the rho 
function used in this example. 


If the value of K generated in the example above is a scalar, not an 
array, then the rho of K is the null vector, a vector of length 
zero - for example: 


Kg 3% 
PK 
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APL simply displays a blank line in response to the ok pened cag ng 
shape of any single scalar, including zero, 1s the null vector. e 
shape of the null vector is zero. This is illustrated in the follow- 


ing example. 
FO 


FCFO) 
QO 


The oX function always returns one element for each dimension of the 
array K. The following is an example of a rho function on a 2- 
dimensional array. 


The expression pA returns the dimensions of A as number of rows, 
followed by number of columns. 


The function ppX can be used to return the rank of K as follows: 


Array ppk 
Scalar 0 
1-dimensional 1 
2-dimensional 2 
3-dimensional 3 


This effect is the result of the fact that pX is a vector containing 
one element for each dimension of K, so its rho, p(pX), is a l-element 
vector consisting of the number of dimensions of K. 


The function pppX returns 1 for all possible K's. 
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2.7.4 po: Reshaping an Array 


Function: Gyadic rho (p); R«XpY 
Argument Domain: 
left! non-negative integers 
right: any 
Argument Shape: 
left: scalar or vector; (ppX)<1 


right: any 
Result Range: same as right argument 
Result Shape: array; pA«->X for a vector 
Origin-Dependent? no 
Take Dimension Argument? no 





The dyadic form of the rho function specifies a new array or reshapes 
an existing one. It is issued as shown in the following example: 


58 5 
where the left argument, 3, specifies the shape of the array to be 
constructed and the right argument, 5, specifies the value to be 
assigned to each element of the array. The shape of the array 
describes both the number of dimensions of the array and the number of 
elements in each dimension. In the example above, a 1-dimensional 
array is created, because only a single value is supplied to the left 
of the p; the number of elements is the actual value of the 

argument, 3. 


The right argument of the dyadic p function may be any shape. 
The example above illustrates the generation of a numeric constant 
array. An array consisting of literal characters can be constructed 
by including a character string as the right argument and enclosing 
it in quotes. A character vector reshaped in this way is displayed 
without spaces, as shown in the following example. 

CRP UG ROLE | 
OBC 
Cee 


The examples included below illustrate the generation of two arrays. 
The first example reshapes an existing array; the second specifies the 
elements of a new array in the rho function. 


Hed 2 3 4 


ops 8 






e4 3 2 4 


The array that is being reshaped need not have the same number of 
values as the array from which values are taken. In the following 
expression: 


£X 4g. ES gs ee 
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If B has more than five elements, then only 
If B has fewer than five elements, then the 
elements in B are repeated as often as necessary, in lage * 
The following example illustrates both of these operations, nile 
shaping a 2-dimensional array and then reshaping it into a vector. 


A requires five elements. 
the first five are used. 





The next example reshapes a character vector into a 3-dimensional 
array. 


OR de) AR COE PGR WK LM OP QRS TUVA t 





ree a 


MPC FE 
(RRS 1 
LEY WHT 


A general rule for the dyadic rho function can be expressed as the 
following: if A+V/oB, then pA+>V and A contains only elements of B. 

A relationship between the rho and ravel (Section 2.7.7) functions can 
also be described as VpB<«-+Vp,B. 


The rho function is often used in conjunction with iota (Section 2.7.5). 
The next example generates an array consisting of consecutive integers. 


Heaee 2er4 
1 2 


3 4 


Any number of array elements can be specified in a dyadic rho function, 
as long as the number is not negative or fractional and does not 
generate an array too large for the user's workspace. 


The rho function may be used to generate a null or empty vector. A 

vector of this kind is often useful in executing APL functions. As 

described in Section 3.4.1, if an empty vector is the argument of a 

branch, then function execution will not branch but will continue to 
the next statement in sequence. 


An empty vector is generated when the right argument of the rho is a 
Scalar. Some examples of expressions that generate null vectors are 
included below. 


oA 
Opt 
0p0 
10 


(where A is a scalar) 
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2.7.5 1: Generating Consecutive Numbers 






Function: monadic iota (1); Rei1Y 
Argument Domain: 








left: — 

right; NON-negative integers 
Argument Shape: 

left: - 





right: scalar or l-element vector 
Result Range: non-negative integers 
Result Shape: vector; pR<-,Y 
Origin-Dependent? yes, result 
Take Dimension Argument? no 






The monadic form of the iota (1) function is used as an index genera- 
tor. It generates a number of consecutive integers, equal to the 
value specified as the argument of the iota, starting from the value 
of the index origin. The following is an example of this function. 


(lee. 4 
43234 

pa 
4 


The argument of the function must be a non-negative integer scalar or 
a l-element array. 


The expression iW generates a vector containing NV components. If the 
index origin is set to 1, these components have values 1 through J’. 

If the origin is 0, then the resulting vectcr has values 0 through N-1. 
The index origin default is 1 in the clear workspace, but this 

setting can be changed by the user by means of the DIO system variable 
(Section 4.2.2) or the )ORIGIN system command (Section 5.4.1), as 
shown below. 


13 
iL 2.8 

JORTGIN O 
wASs 1 

13 
O12 


The monadic iota function can be used in any expression to generate 


consecutive results. The following example illustrates the use of 
iota in generating powers of 2. 


2x110 
1 248 16 32 64 128 256 S12 


Iota is often used in conjunction with rho. 


To generate a vector with the same number of entries as array X, the 
user can specify the expression shown below; in this case, array X 
contains four elements. 
Kt7 1 3 4 
wares 
12 3 4 
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As illustrated in the following example, the index generator function 
can be used to generate a null or empty vector; the shape of a null 
vector is always zero. 


1d 


(APL outputs a blank line) 
FLO 
0 


This function may also be used to determine the value of the current 
index origin: 
vl 
it (index origin is 1) 


6) (index origin is 0) 
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1: Finding the Index of a Value 


Function: dyadic iota (1); R«X1Y 
Argument Domain: 

left: any* 

right: | any* 
Argument Shape: 

left; vector; (ppX)<s1l 


tight: any 
Result Range: non-negative integers 
Result Shape: scalar or array; pRpY 
Origin-Dependent? yes, result 
Take Dimension Argument? no 





The dyadic form of the index (1) function locates the first occurrence 
of a particular value in a vector - for example: 


ae 
. 


49 6 8 


& 


3 


y 


ce a 


The value of Y occurs as the third element of vector X¥. When using 
the dyadic form of iota, X can be scalar or a vector and Y can be 
any scalar or array. 


The index function can be used to locate a particular type of value in 
a vector. For example, to find the index of the largest value in X, 
the following is specified: 


(eae if /# 


KEAa] 


sbnetbeihch: BER. ssh 
RES UP ALE] 


The right argument of the index function may be an array. If B is the 
vector: 


BeQ 1 2 3 4 G2 & ? BP 


and A 


6 
3 
OG 


is a 2-dimensional array: 


a) 
a 
ie 


9 


then the following can be specified: 


Hed pA 


Ae 
oy 


The result of a dyadic iota function X¥+BiA always has the same shape 
as the right argument of the function - formally pX¥++p4. If Aisa 
matrix, then the correspondence between A and X can be expressed as 
follows: X{[i;/] is the smallest X such that A[I;J] is equal to B[X]. 


*Both 
types cannot be mixed in the same function. 


arguments must be either character or numeric; argument 
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The right argument of the function can be an array of literal charac- 
ters, as shown below. 
TORCUEF GH! y UME ORET ! 

85 145 4 
If the array identified by this argument contains a number or literal 
that cannot be found in the left vector, then APL responds with the 
next index number after the last element of the vector. In the follow- 
ing example, APL tries to locate the numbers 1, 2, 3, and 4 in vector 
V. There is no occurrence of 1 in the 6-element vector, so the next 
available index, 7, is displayed as the index of l. 


Vet 42 3 7 & 
Bem 2PL4 
VA 

* 6 

4 2 


The next index number can be expressed as 1+p/. 


The examples included so far in this section have assumed that the 
index origin setting is 1. If the origin has been set to zero, index 
values are returned as shown in the example below. 


TORCOEF !y toM! 
3 7 

JORIGLH O 
WAS 7 

HA RROKUER 1 tases 
2S 
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2.7.7 ,: Converting a Value to a Vector 


Function: Monadic ravel (,); R+,Y 
Argument Domain: 

left:  - 

right: any 


Argument Shape: 
left: ~ 
right: any 

Result Range: same as argument 

Result Shape: vector; pR«>x/pY 

Origin-Dependent? no 

Take Dimension Argument? "O° 





The monadic ravel (,) function constructs a vector from any scalar or 
array. The following example illustrates the use of the ravel func- 
bak tion in transforming a 2-dimensional array into a vector. 


be 
ui he 
oh id 


Heke yA 
123 45 6 
fg ks 
& 


The vector produced by ravel has the same number of elements as the 
original array. The elements of the array are preserved in the result- 
ing vector in row major order. If the argument to the right of the , 
is already a vector, then B<>+,A. 


The ravel function may be used to transform a scalar value into a 
single-element vector. If A is a scalar, then ,A produces a vector 
containing one element: 


A+,A 


Note below the difference between the shape of a scalar (null vector) 
and the shape of a scalar to which the ravel function has been 
applied. 


o4 


ar (APL outputs a blank line) 
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2.7.8 ,: Catenating and Laminating Variables 


Function: dyadic catenation (,); R+«X,Y 
Argument Domain: 

left: any* 

right: any* 
Argument Shape: 


jeft: array 

right: array 
Result Range: same as argument 
Result Shape: array 
Origin-Dependent? no 
Take Dimension Argument? yes 





The dyadic catenation and lamination (,) functions are used to chain 
scalars or arrays together to form a new array. Catenation joins 
variables together along an existing dimension; lamination joins them 
together along a new dimension. The following example illustrates the 
catenation of two vectors to each other and to several scalar values. 


aes @ 9 
Bed 2 
ey 
uw 8 9 6 ? 
LGeAy hy fo 
19 3 8 9 4&4 7 12 


Any number of items can be catenated. The order in which values are 
catenated is the order in which they are specified in the APL state- 
ment. The result of a catenation can be expressed as follows: 
Lf pA++5 and pB+>3, then pR<A,B is 8, ROiS]++A and #[5+13]<«+2. 


Catenation is useful in adding new subtotals to a grand total or for 
inserting new elements between existing elements of a vector. The 
following example illustrates the insertion of the scalar value 6 in 
vector A. 


fel 23485 78 9 16 11°12 
Te AeA Te Ge AL Se CP AY EY 
L2345 467 8 9 10 11 12 


Literal values can also be catenated, as shown in the following example: 


TRMHE Fy bee 
MAME RCT 


APL does not allow the user to catenate numbers to literal characters 
and displays a DOMAIN ERROR if such an operation is attempted. 


The dyadic catenation function may also be used to joint multi- 
dimensional arrays together along an existing coordinate. The user 
includes this integer coordinate number in brackets in the function 
specification. If the coordinate is omitted, APL assumes the last 
coordinate (1 or the rank of the array, whichever is larger (1ifppA)). 


*Both arguments must be either character or numeric; argument 
types cannot be mixed in the same function. 
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For a 2-dimensional array, APL extends along the second dimension, 
thus adding a column, as shown in the first example below. In the 
second example, the scalar value 0 is catenated with the array A along 
the coordinate specified by the user; this has the effect of adding a 
row. As discussed in 2.6.2, APL extends the scalar argument, 0, to 
the array on an element-by-element basis. 


Me2 FF VS 
y () 


+ #2 3 0 

4 5 6 9 
Ay TAO 

i 2 3 

4 3 6 

oO O 9 


A scalar value can be included in the catenation function, as shown 
in the following: 


Ay? 
a 
& 7 


CF ba 


1 
4 


Both arguments of the catenation function may be arrays. [In the fol- 
lowing example, the arrays are of equal size. 


ae 
ay 


8 7 
2 9 4 
i 
Oo 4 2 
%* 4 5 
Sol Lar 
8 7 3 
2 9 4 
oO 1 2 
5 4 5 


wy T 
8 7 3 90 ft 
2 9° 424 3 A 


qn ts 


The next example illustrates the catenation of two arrays of different 
sizes. 


Bem BRS 
Co) 

1 2 3 

4 3 6 
BER BRO 
& 

7 8 Mg 

10 di 12 

13 44 1% 
PCO, LE 
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ua 3 
c 
| 2 3 
4 ba é 
? 8 9 
1 Oe i a 
13 #414 #15 


Three general rules can be established for catenating arrays according 
to the form 4,[K]B. If a catenation expression does not conform to 
any of the rules presented below, it is not a legal APL expression. 


Lis If the arrays have equal dimensions ((pp4A)=o90B), then 
K must be in ipod and pA must equal eB except in the 
Kth dimension. This is illustrated in the following 
example: 


Pe 


Here A is equivalent to R#£;14;] and B to AE;4+163;]. 


2 If the arrays have different dimensions ((opA)#ppB), 
then 2 must have one fewer coordinates than A or vice- 
versa (1=|(ep4)-ppB) and pB must equal pA without its 
Kth coordinate. This is shown below. 


ACS 4 SPO 
Bed SeO 
fig y 


LENGTH EF RO F: 
Fig Ly Ke 


4 
fig Aly [1 TE 
pre 
445 
Here, A is equivalent to R#{13;;] and B to R[4;;]. 
3. If one of the arguments is a scalar, then the scalar 


element is expanded and applied to the array on an 
element-by-element basis along the Xth dimension, as 
described in Section 2.6.2. 


Lamtnatton differs from catenation in that it joins variables along 

a new coordinate. The APL syntax is the same for catenation and 
lamination. However, the coordinate specification ([K]) is fractional 
in a lamination expression, indicating a position between existing 
coordinates in which the new coordinate is to be placed. If the two 
arguments in @ lamination function do not have the same dimensions, 
then at least one of them must be a scalar value or APL will not accept 
the function. 


The following examples illustrate some applications of the lamination 
feature. 


AERC 
EF 


2 


an 
RE 
OF 


uv 


TE 


OK 
OX 


RE 





Crs 
RY 


Ww 
ts 
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(exe ARC'ZLO,57' ORF! 


py 


eke (ORC CL, Sy ers 


(eles Op UVWws re! 


Ae 3 Op ARC UEF | 
Ay, ge 


Ay fl. Pe 


Ay le. Fy 


ats 


ayC 57's! 


Tatty Td. 
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TE 
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2.7.9 /: Compressing an Array 


Function: dyadic compression (/) ;R<X/[KIY 
Argument Domain: 

left: Booleans (0,1) 

right: any 
Argument Shape: 

left: scalar or vector 


right: scalar or array 
Result Range: same as right argument 
Result Shape: array; popR<>poY 
Origin-Dependent? no 
Take Dimension Argument? yes 





The dyadic compression (/) function builds a new vector or array from 
an old one by specifying the elements to be deleted and those to be 
preserved. The right argument of the function may be any array. The 
left argument must be the scalar argument 0 or 1 or a boolean vector 
(a vector containing only 0's and 1's). The compression function 
operates as shown below. 


Hes 7 FS Li 7s 
Be] 1 Oo 1 6 
[Te Hh ei a 

ay dd 


Elements in A whose positions correspond to the positions of 1's in 

B are preserved; elements corresponding to 0's in B are dropped. 
Because only 0's and 1's are valid values for B, the number of elements 
in the resulting array can be expressed as +/B. If B contains only 
1's, all elements of A are preserved; if B contains only 0's, the 
result is the empty vector. 


The lengths of A and B must generally be the same. However, if A is 
of length 1, it will automatically be extended to the length of B; if 
B is of length 1, it will be extended to the length of A. Thus: 


Aes 7 F Li is 
Be] od Oo 10 
B/S 


L/Aa 
27 9 dA 13 


OLA (APL outputs a blank line.) 


The expression 0/A produces the empty vector, because all elements of 
A are dropped. 


As discussed in Section 2.7.2, a compression function may also be 
specified for one particular coordinate of a multi-dimensional array 
by including the coordinate number in brackets. For a matrix, com- 
pression along the first coordinate may cause certain rows to be 
omitted; compression along the second coordinate may cause columns to 
be dropped. The result in all cases is a matrix. Several examples of 
arxay compression are included below. These cxamples also illustrate 
the defaults which APL supplies when the coordinate number is omitted 
from the function. 
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9 10 di 12 
1 oo 2 O/ff2 74 


1 3 
oS 7 
9 qi 
rosa 
3.0 
Ke? BEG 
oO 1 L747 
2 & 
mo _—e (Compress along last dimension) 
1 es 3 


(Compress along first dimension) 


The shape of the result of a compression function can be expressed as 
follows: if R+B/[ KIA, then ppR+>ppA. 
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2.7.10 \: Expanding an Array 


Function: dyadic expansion (\); R«X\[KJY 
Argument Domain: 

left: Booleans (0,1) 

right: any 
Argument Shape: 

left; scalar or vector 


right: SCalar or array 
Result Range: same as right argument 
Result Shape: array; ppRhppY 
Origin-Dependent? no 
Take Dimension Argument? yes 





The dyadic expansion (\) function builds a new vector or array by 
expanding the elements of another array into a new format. Expansion 
is the converse of compression (see Section 2.7.9). The right argu- 
ment of the function may be any array. The left argument must be the 
scalar value 0 or 1 or a boolean vector containing only 0's and 1's. 
The expansion function operates as shown below. 


Be 1S 
Vel O 1 O 1 
Ve 
1 Oo 2.0 3 
VA DAF. ! 
mF hk 


The function expands the elements of A into the format specified by /. 
The values of A are inserted in positions corresponding to the occur- 
rence of 1's in VY. For numeric values, zeroes are inserted in posi- 
tions corresponding to 0's in the boolean vector. If the right argu- 
ment is a character string, as in the second example above, spaces are 
used rather than zeroes. 


The number of 1's in the boolean vector must generally be the same as 
the number of values in the array included as the right argument. 
Thus, +/V must be equivalent to pA. However, a scalar boolean value 
as the left argument of the function is extended as shown below. 

1 oO ING 

oO 8 

As discussed in Section 2.7.2, an expansion function may also be 
specified for one particular coordinate of a multi-dimensional array 
by including the coordinate number in brackets. Several examples of 
array expansion are included below. These examples also illustrate 
the defaults which APL supplies when the coordinate number is omitted 
from the function. 
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2.7.11 +: Taking Array Elements 


Function: dyadic take (t); R<Xty 
Argument Domain: 

left: integers 

right: any 
Argument Shape: 


left: scalar or vector; (oX)<*po0Y 
right: any 
Result Range: Same as right argument 
Result Shape: array; pf+>|X 
Origin-Dependent? no 
Take Dimension Argument? no 





The dyadic take (+) function builds a new vector or array by taking 
a specified number of elements from an existing array. The right 
argument of the function may be any array. The left argument can be 
a one element array or scalar, or a vector. The number of elements 
in the left argument must be equal the number of dimensions in the 
right argument. A scalar is treated as a one element vector. 


The take function operates as shown below. 





This expression takes the first two elements of VY and forms a new vec- 
tor. If the value of the scalar is greater than the number of ele- 
ments in VY, then the resulting vector, X, is extended so that its 
length is the value of the scalar. As shown below, zeroes are used to 
extend a numeric vector and blanks are used to extend a character 
vector. 
Bers 
1 2 
Af is 
i123 06 
Fle Los APL TL! 
APL | 
10 


In the expression #&+StV, if S is positive, then R consists of the first 
S elements of VY. If S is negative, then RF contains the last |S ele- 
ments of 7. If |S is greater than the number of elements in V 
((|S)>oV), then zeroes or spaces are inserted in FR before or after 
the values of VY. Examples of the effects of negative scalars are 
included below. 
“Sele 24 36 48 
00 12 24 34 49 
“1LOF FOO4S! 
FOO4S 
OPUS 
2 3 
A take function may also be specified for a multi-dimensional array. 
In this case, the left argument of the function must be a vector 
containing one element for each dimension of the array. In the 
expression StV, the value of S[1] indicates the number of elements to 
be taken along the first coordinate of VY, and so on. Several examples 
of taking an array are included in the following. 
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Feles SrrwUis 


2 3 4 a 
7 8 ? 0 
120613 #14 «15 
2 RA 
3 
190 
“Hh HA 
Q 
2 
7 
12 


The shape of the result of the take 
function can be expressed as follows: 
if R«A+B, and ppR<>ppB, then pk<>|A. 
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2.7.12 +: Dropping Array Elements 


Function: dyadic drop (+); RX W 
Argument Domain: 

left: integers 

right: any 
Argument Shape: 


left: scalar or vector; (pX)<*ppY 
right: any 
Result Range: same as right argument 
ResultShape: array; pR(pY-|X) 
Origin-Dependent? no 
Take Dimension Argument? no 





The dyadic drop (+) function builds a new vector or array by 
dropping a specified number of elements from an existing array. 
The right argument of the function may be any array. The shape 
requirements for the arguments are the same as for the take func- 
tion (2.7.11). 


The drop function operates as shown below. 


Me Ve ud 
Lo 2 3 4 3 
ea] Bad 


(ee 5 





34 °5 


This expression drops the first two elements of V and forms a new vec- 
tor with the remaining elements. If the value of the scalar is 
greater than the number of elements in V/V, then the result is the null 
vector. 


The drop function handles negative scalar values in much the same way 
as take. The function R+ StV causes the last |S elements of VY to be 
omitted from vector RF. The following is an example of the effect of a 
negative scalar on a drop function. 


wd SS 


t 23 


A drop function may also be specified for a multi-dimensional array. 
In this case, the left argument of the function must be a vector con- 
taining one element for each dimension of the array. In the expres- 
sion S+¥V, the value of S[1] indicates the number of elements to be 
dropped along the first coordinate of VY, and so on. The examples 
below illustrate the use of drop in multi-dimensional arrays and 
demonstrate the construction of identical arrays by means of alterna- 
tive take and drop functions. 


eae de Be vds 
i 2 3 4 S 
o y 8 ? 10 
$1 a2 413 #14 «15 


2 "208 
4 § 
F 10 
“1 34a 
4 5 
9 10 
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The following example illustrates the use of drop in a character array. 


(eae? &% 4p  ABCURFGHTUKLMHOPRRSTUVA | 
ABCT 
EF GH 
KOKL 


MHOF 
Qh ST 
LIM Wot 
12 ava 


LO aya 
CUR 
ST 

Poa oR dye 
Oo 0 0 
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2.7.13 &: Transposing the Dimensions of an Array 


Function: monadic transpose (&) ;R+QY 
Argument Domain: 

left: - 

right: any 
Argument Shape: 


left: — 

tight: any 
Result Range: same as argument 
Result Shape: array; pR+>OpY 
Origin-Dependent? no 
Take Dimension Argument? no 





The monadic transpose (Q) function interchanges the dimensions of any 
array. For a matrix, this function has the effect of exchanging the 
rows and columns. The symbol & is formed by overstriking the circle 
© with the backslash (\) character. The following is an example of 

a simple matrix transposition. 


fee? Sr 1G 
1 2 og 
4 3 4 

FR 


Ae QA 

hy 
4S 

pea 


Note that the & function changes the shape of the array from 2~by-3 
to 3-by-2. For a matrix, the monadic transpose function often per- 
forms the same operation as the dyadic transpose function described 
in Section 2.7.14. 


A transposition for a 3-dimensional array is shown below. 


eg 2 B18 


ae 
nN 


5 4 
Oo 6 
7? 
Qe 
1 3 
4’ 7 
2 6 
4 8 


If the right argument of the monadic transpose function is a vector 
A, then ®4<+5A. The shape of the result of the monadic transpose 
function can be expressed as follows: if R+XA, then opR+>0pA and 
oR+>o0A. 
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2.7.14 (&): Transposing an Array 


Function: dyadic transpose (&) ;R<X8[KIY 
Argument Domain: 

left: non-negative integers 

right:any 
Argument Shape: 


left: vector; (pX)<-poY 

right: any 
Result Range: same as right argument 
Result Shape: array 
Origin-Dependent? yes, left argument 
Take Dimension Argument? yes 





The dyadic transpose (&) function restructures an array of any shape. 
It can be considered an extended version of the monadic transpose and 
in some cases has the same effect on a matrix as the monadic function - 
for example: 


eee? SF 


i. 2 s 
4 8 4 
i] ri 
1 4 
2 
3G 
2 LA 
1 4 


nS 


8 


The right argument of a dyadic or scalar & function may be any array. 
The left argument must be a vector containing one element for each of 
the dimensions of the array to be transposed. The shape of the vector 
expresses the rank of the right argument. For the function V&A, this 
can be expressed as the following: pV must equal ppd. Thus V must 
have two elements if A is a matrix, three if A is a 3-dimensional array, 
and so on. A scalar argument is treated as a one element vector. 


The dyadic transpose function rearranges the dimensions of an array 
by transposing them according to the vector provided as the left 
argument. The following illustrates an existing array and the way 
in which a new array is developed by transposing its dimensions. 


ro) 
1 2 
oF 4 
y 190) #ii 


me Od 


bh 


13 14 iS 16 

L7 48 19 20 

21 22 23 24 
pA 


If the following APL statement is specified: 


3 lL 2A 
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then the vector supplied as the left argument is used to rearrange 
the dimensions of A as shown below. The elements of the vector 
determine the new positions to which the elements of pF are to be 
moved. 


(left argument) 3 + 2 
(Shape of A) 2. 3 3A 


(Shape of result) oR 


The new array has the structure shown below. 


Res 1 2wA 
Fi 

1 13 

2 14 

3 1S 

4 16 

n 1? 

é 18 

? LY 


tad 20 


$ md 
LO HQ 
Ll 28 


12 34 


The examples included above illustrate the case in which the 
coordinates of the original array are permuted. In a permutation, 
all of the coordinate numbers are the same, but they are arranged 

in a different order; for example, 3 1 2 is a permutation of 1 2 3. 
In the function V&A, if V is a permutation of ippd, then the follow- 
ing is true. If K represents a coordinate of array A and the func- 
tion R<«V8A is specified, then R is an array similar to A except 

that the Xth coordinate of A is the V[K]th coordinate of RP and (pF) 
[V] is equal to pA. 


In a dyadic transpose function, it is also legal to specify as the 
left argument a vector which is not a permutation of the coordinates. 
Two or more of the elements may be identical. Legal values for the 
elements of the vector must follow these rules: 


e Each element of the vector must be a positive integer 
that is less than or equal to the rank of the right 
argument (VeuippA). 


e All of the positive integers up to the largest in the 
vector must appear in the left argument ((1i//V)eYV). 
In a 3-dimensional array with shape 2 3 4, valid vectors 
fomigia F753, Lia, Li a, 22 3,214, 12 2, 8 2 4, 
and 2 12. Invalid vectors are 3 11, (2 is missing) 
22 2, (1 is missing), and 2 3 2 (1 is missing). 


Incomplete vectors have special meaning in the dyadic transpose 


function. Only particular elements will be selected by the vector, 
as shown below. 


Nr 


A 


Eu 
2 


di 
2 


THE 
Vector Selects 
1 Elements whose 
are the same 

2 Elements whose 
1 same 
1 Elements whose 
2 same 
Hh Elements whose 
2 same 


2 


2 
1 
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first, second, and third indices 


first and second indices are the 


second and third indices are the 


first and third indices are the 


The elements selected by this vector will be transposed as shown in 


the examples below. 


Such dyadic transpositions effectively take 


slices through the array along different diagonal directions. The 
first example below obtains the main diagonal of the matrix. 


4 


Lid 


Ae? Bris 


eh 
2 & 
ou OG 
1 1aa 
Ae? 3 dP 124 
7) 
2 a 4 
6 F § 
1O di de 
14° $15 16 


18 49% 20 
22 23 24 
2 1 Lae 
13 
1s 
2g 


The following examples illustrate dyadic transpositions of a 
character array, 


ARCH 
EF GH 
WK b. 


MRECIF 
QRS T 


LW We 


64 Fr 


AE T 
bay 


f 
< 


GkECn 
QkST 


eae 2 4p ABCUEF GH EUKL MOF RRS TUVWH | 


L 2 jaa 
1 2 ia 
1 od 2a 
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PET 
MQU 


EF 
MAY 


UGK 
OSwW 


CH 
TM 


Table 2-5 may be helpful in determining transpositions for a variety 
of arrays. 


Table 2-5 
Transpose Definitions 


R<V 

R+<M 
(pM)C2 1] RLI3SI<MEI37] 
L/p™M REITI+MCI3I] 
oA R+A 


(pA)C1 3 2] RIT;J;KI*+ACI3K37] 
(pA)03 1 2] RUIsJ3KI]+ACI3K3I] 
(pA)(2 3 1] RUIsd 3 KI+ALK3I37) 
(L/(pA)01 23),(p4)03] R(I3;71+ACI3I37)] 
(L/(p4)01 33),(p4)02] RUI3JI+AlI3J3I] 
CL/(CpAYE2 33), 0pA)E1I R{(I37+ALI3I3T) 
L/pA RU(II+<ACI3I;7) 
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2.7.15 $: Reversing an Array 





Function; monadic reverse (0); R+d[KIY 
Argument Domain: 
feft: - 
right: any 
Argument Shape: 
left: - 
right: scalar or array dimension 
Result Range: same as argument 
Result Shape: array; pi<pY 
Origin-Dependent? no 
Take Dimension Argument? yes 













The monadic reverse ($6) function is used to reverse a vector or the 
elements of one coordinate of a multi-dimensional array. The symbol 
6 is formed by overstriking the circle o with the vertical line (|) 
used for absolute value. The reverse function differs from transpose 
in that it changes the order of an array, not its structure, The 
following is an example of reversing a vector, 


Mrs 


As discussed in Section 2,7.2, the reverse function may also be 
specified for one particular coordinate of a multi-dimensional array 
by including the coordinate number in brackets. Several examples 

of array reversal are included below. These examples also illustrate 
the defaults which APL supplies when the coordinate number is omitted 
from the function. 


eaee ae. 


1 2 3 4 
oS & 7 & 

Pe. ya 
Gi & 7 € 
: 2 3 4 

Pee pe 

3 2 i 

@ 7 6 5& 

ape 
4 8 2 i 
& 7 & & a ‘ 

— (Reverse last dimension) 
ba] J ? 4 : : - 
L . “4 : (Reverse first dimension) 


It is possible to reverse a matrix in both of its dimensions. This 
is not the same as transposing the matrix, as is indicated in the 
examples that follow, 


(lesen SPUS 


i #2 3$ 

4 4 4 
ward as 

6& 3S 4 

o 2 1 
ye 

1 4 
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2.7.16 $: Rotating an Array 





Function: dyadic rotation (0); R<XO[KIY 
Argument Domain: 

jeft; integers 

right: any 
Argument Shape: 

left; Scalar or vector 

right: Scalar or array 
Result Range: Same as right argument 
Result Shape: array; ph«-pY 
Origin-Dependent? no 
Take Dimension Argument? yes 













The dyadic rotate (¢) function is used to rotate an array by a speci- 
fied number of places. The right argument of the function may be any 
array. The left argument may be a scalar or a vector. The following 
example illustrates two rotations of a vector; note that a positive 
rotation causes a left shift and a negative rotation causes a right 
shift. 


Bb US 
45 12 3 

"Sas 
445 12 


If a vector is being rotated, the left argument of the function must 
be a scalar or a l-element vector. 


A rotation function may also be specified for a multi-dimensional 
array by including the coordinate number in brackets. If a multi- 
dimensional is rotated, the left argument of the function must be a 
scalar, a single-element vector, or an array whose elements correspond 
to the dimensions of the array to be rotated, with the dimension 
being rotated omitted from the array. For example, if a matrix 
containing three rows and four columns is rotated and a vector is 
included as the left argument of the function, that vector must 
contain three elements if the rows of the matrix are rotated and four 
elements if the columns are rotated. A scalar left argument will be 
extended to an array of proper shape. This is illustrated in the 
following examples. 


Hes gp ARCIEP GHD Wt Kit 


ARCE 
EF GH 
KOK L 
Oo 1 2a 
ABC 
GHE 
Kid 
12 2 SeCias 
RF KI 
LICH 
ARGL 


Negative values in the left argument are handled as shown below. 
These examples also illustrate the defaults which APL supplies when 
the coordinate number is omitted from the function, 
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(lee Sp ASCUEF GM TUKL MUO! 
AERCIE 
FGHIJ 
KLMHO 
1 “i 2 2 284 
FL MMO 
KECIUE 
AGHIG 
a 2 “1a 
CVE CUE 
HIJFG 
KL MH 


The shape of the result of a rotation function can be expressed as 
follows: pR+>pB if R+Ad [K] B, then pA<> (K # 19pB)/pB. 
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2.7.17 4: Sorting an Array in Ascending Order 


Function: monadic grade-up (A); R+<ALKIY 
Argument Domain: 

left: —- 

right: any 
Argument Shape: 

left: - 


right: Scalar or array; (ppY)<2 
Result Range: non-negative integers 
Result Shape: vector; pf++(o¥) [K] 
Origin-Dependent? yes 
Take Dimension Argument? yes 





The monadic grade up (A) function aids in sorting an array in ascending 
order. The grade up function is extended to operate on matrices as 
well as vectors. The argument of the function represents the scalar, 
vector, or matrix whose elements are to be recorded. The array being 
sorted may contain either numeric or character elements. 


If two or more elements of the array being sorted have the same value, 
then the order of the elements is determined by their relative 
positions in the original array. 


The symbol 4 is formed by overstriking the delta (A) character with 
the vertical line (|) used for absolute value. 


The following example illustrates the use of the grade up function 
in sorting the elements of a vector. 


Ae2 FG 2 4 SF 10 4 
[he Be ge 

137 43 2 64 
[TE 

234479 10 


Note that the grade up function does not actually sort the vector. 

It creates a permutation vector of the index numbers of the elements; 
this vector is then used to sort the original vector, as shown in the 
examples above. 


The current setting of the index origin determines the index values 
returned by the grade up function, An example of this is included 
below. 
Mee 7 S 1 2 
ax 
43 132 
JORIGIN O 
was 4 
Ay 
32402 1 


As discussed in Section 2.7.2, the grade up function may also be 
specified for one particular coordinate of a matrix by including the 
coordinate number in brackets. APL supplies defaults when the 
coordinate number is omitted from the function, as shown in the 
examples below. 
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If the array to be sorted by the grade up function is a matrix, the 
simplest operation causes each row of the matrix to be treated as a 
string. The result of the grade up function is a vector whose length 
is equal to the number of rows in the matrix. The following examples 
illustrate the sorting of two matrices - one character and one 


numeric. 
A 
STEVE 
SAM 
STAN 
pA 
3 5 
A {Sort along last dimension) 
2 3 
ACAA;] 
SAM 
STAN 
STEVE 
B 
3 2 4 S 0 
3 1 9 7 #0 
3 2 0 8 0 
oB 
3 OS 
-— - (Sort along last dimension) 
BCAB;] 
3 i. 9 #7 0 
3 2 (6) 8 0 
3. 2 4 97 © 


meee tee included above cause the matrix to be sorted by rows; 
s , by subscripting the function, as shown below, it i i 
© sort on the basis of columns, : ere 


A 
SSS 
TAT 
EMA 
VN 
£ 


pA 
P 
ahs (Sort along first dimension) 


ACL3;40114] 
SSS 
ATT 
MAE 
NY 
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2.7.18 Y: Sorting an Array in Descending Order 





Function: monadic grade-down (V¥); R<«¥IKIY 
Argument Domain: 
left: —- 
right: any 
Argument Shape: 
left: - 
right: scalar or array; (ppY)<2 
Result Range: non-negative integers 
Result Shape: vector; oF<>+(oY)(K] 
Origin-Dependent? yes 
Take Dimension Argument? yes 










The monadic grade down (VY) function aids in sorting an array in 
descending order. The grade down function is extended to operate on 
matrices as well as vectors. The right argument of the function 
represents a scalar, vector, or matrix whose elements are to be 
reordered. The array being sorted may contain either numeric or 
character elements. 


Duplicate values are handled exactly as in the grade up function; the 
order of such elements is determined by their relative positions in 
the original vector. As in the case of grade up, the index origin 
setting determines the values returned. 


The symbol Y is formed by overstriking the del (V) character with the 
vertical line (|). Following are several examples of using the grade 
down function to sort the elements of a vector. 


ey 


S37 31 24s 
flekepa 

2 ie area 
ALE 


YS 43 2 21 
ACvacS 7 Si 2 4 2] 


Pi 43221 


uh 


Like the grade up function, Y creates a permutation vector that can 
be used to sort the original vector. The last two examples above 
illustrate the way in which grade down and indexing operations can 
be performed together. The grade down function operates on matrices 
in the same way as that described for grade up, except that it sorts 
the elements of the matrix in descending order. 
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2.7.19 ?: Rolling Random Integers 


Function; mMonadic scalar roll (?); R+?Y 


Argument Domain: 

left: ~ ' : 

right: non~negative integers 
Argument Shape: 


left: ~ 
right: any 
Result Range: non-negative integers (0<Y) 
Resuft Shape: array; pR<pY 
Origin-Dependent? yes 
Take Dimension Argument? no 





The monadic roll (?) function is used to generate an array of independ- 
ent random integers. Roll is actually a scalar rather than a mixed 
function, but it is presented here because it is closely related to 

the dyadic deal function (Section 2.7.22). 


The argument of the roll function is an array of positive integers. 

The shape of the array produced by the expression R+?4A is the same as 
the shape of A. If the current index origin setting is 1, each ele-~ 
ment in RF is a random integer in range 1 through the value of the 
corresponding element in A. If the origin is 0, the range is 0 through 
the value of the corresponding element in A minus 1. An example of a 
roll function performed on a vector is included below. 

_] 


PS 1 
39 4 13 4 


n 


O15 20 25 


Note that the number 4 was generated twice, once as a random integer in 
range 1 through 15 and once in range 1 through 25. ‘This can happen be~ 
cause numbers selected by roll are independently random within each 
range. The term "roll" relates to the analogy between the operation 
performed by this function and the rolling of several dice. The deal 
function differs from roll in that it generates a set of random num- 
bers in which no number is selected twice. 
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2.7.20 ?: Dealing Random Integers 


Function: dyadic deal (?); R«X?Y 
Argument Domain: 

left; non-negative integer (Y<Y) 

right: ROnN-negative integer 
Argument Shape: 

left: Scalar 


right: Scalar 
Result Range: non-negative integers (0<Y) 
Result Shape: vector; pR<*,X 
Origin-Dependent? yes 
Take Dimension Argument? no 





The dyadic deal (?) function generates a vector of integers randomly 
selected from another vector; no number may be selected more than once. 
Unlike the roll function, which can be compared to rolling several 
dice independently, "deal" refers to the analogy of dealing a number 
of cards from a deck containing no duplicates. 


Both arguments of this function must be positive scalars or single- 
element arrays. The length of the vector produced by the expression 
R+A?B is the same as the value of A. A identifies the number of 
elements to be selected randomly from the values in range 1 through 8B 
if the index origin is 1, or 0 through B minus 1 if the index origin 
is 0. The value of A must be less than or equal to the value of 

B (ASB). Several examples of the deal function are included below. 


1243 5 
PLE SO 
& 19Q6SAS07E42]9 7 P4GSSSPSSGE+29 2. P44 321859 E+ 29 FiPSP7ERQIGGE+ 29 
1.50111 2165F+29 
JORIGIN O 
was 4 
we 


3140 2 


Note in the first and last examples that if the values of the two 
arguments are the same (A+B), then the resulting vector is a permuta- 
tion of 1B. 
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2.7.21 tT: Constructing a Character String 


Function: monadic guote (T); R<TY 
Argument Domain: 

left: numbers 

right: numbers 
Argument Shape: 


left: — 

right: any 
Result Range: null or characters 
Result Shape: vector 
Origin-Dependent? no 
Take Dimension Argument? no 





The monadic guote (tT) function converts numeric values to character 
strings and may be helpful in preparing text to be processed by the 
execute function. The argument may be a scalar or an array and may 
have numeric or character values. If the argument is numeric, it will 
be converted to a character string as shown below. 

Kel oR 4 

Cle Peps 


12 3 4 
fy 
Oe SPS 
Dt ee op A 

lL @ $ 

4 5 4 


Pe 


"LE BASS ! gt 
a, 4 AL aie a a 
Cth) ¢& 


O06 090 6 


In the second example above, array A is converted to a 20-character 
vector (spaces output by APL are included in the size) in which the 
character representations of 1 through 6 are members but the corre- 
sponding numeric values are not. 


If the argument is already a character string, then special processing 
is performed to determine whether or not the string represents APL 
identifier (i.e., a variable or function name). If the character 
string is not defined as an identifier, TA returns the null vector. 
If A is defined as a variable, TA returns the value of the variable, 
converted to a character string. If A is defined as a function, TA 
returns the lines of the function definition, separated by pairs of 
carriage return/line feed characters. Examples of these uses of the 
quote function are included below. 

Ae] 2 3 4 

i) $+ Ek go + iy 

123 4 
Fr & 


Bop OE ee ee ye 
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YEEA G & 
C1] Fe CBxA+ axe 
C27 =e2n2 
cai 

2G 1 
100 

[letey Gs 

7 Zea G # 
He (ZXA)+4xB 
BeEZeQ 


46 





STMT AR ERROR: 


hh 


G 4 
t 
1.00 


Note that the definition of function G is effectively restored by the 
use of the character string that represented this function in an exe- 
cute operation. 
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2.7.22 1: Representing a Number in Another Base 


Function: dyadic encode (1); A«XTY 
Argument Domain: 

left: numbers 

right: Numbers 
Argument Shape: 


left: numbers 
right: numbers 
Result Range: numbers 
Result Shape: array; pR<>(pX) ,pY 
Origin-Dependent? no 
Take Dimension Argument? no 





The dyadic encode (rT) function is used to represent a scalar or an 
array in any number system. It is sometimes called the representation 
function. The right argument identifies the scalar or array to be 
translated. The left argument is a vector or scalar that represents 
the number base in which the value is to be expressed; the vector con- 
tains one element for each column of the representation. For example, 
to encode the decimal value 7 in four columns of binary representation, 
the following function may be specified. 


2 2 Br? 


mh 


Oi) 


It is often useful to specify mixed bases for the number to be repre-~ 
sented. The encode function can be used to express some number of 
inches in miles, yards, feet, and inches, or some number of millisec- 
onds in days, hours, minutes, seconds, and milliseconds. The following 
are examples of these and other similar situations. 


0.1760 3 127273125 
4 346 2 5 (miles, yards, feet, inches) 
0 24 60 60 1000+719732523 
8 7 S35 32 448 (days, hours, minutes, seconds, 
04 2 2:16 3 1207100001 milliseconds) 
100185 2 41 (gallons, quarts, pints, cups, 
O 3 320 5.5 3 12+100001 tablespoons, teaspoons, drops) 
Oo 1184 52 5 (leagues, miles, rods, yards, 
0 12 8 3 20r100001 feet, inches) 
174221 (pounds, ounces, drams, scruples, grains) 


In the expression AtTB, A is the representation rule to be applied to 

B. Each element of the vector 4 is defined in terms of the element 
immediately to its left. Thus, in encoding a number as miles, yards, 
co and inches, the following elements are specified from right to 
eft. 


e 12 inches in 1 foot 
e 3 feet in 1 yard 
® 1760 yards in 1 mile 


A miles specification is desired, but is not being defined in terms 
of another quantity, so 0 is inserted in the miles column, as follows: 


O 1760 3 127273125 
4 346 2 5 
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The following examples of base 3 conversions demonstrate the specifi- 
cation of different numbers of columns in the rule vector and illus- 
trate the way in which negative numbers are encoded. 


3B Bri? 
La 

3 Br? 
a 4 

33 3x71? 
4,8 4 


Another useful application of the encode function is shown below. 
Here the integer and fractional portions of a number are returned. 


ReBoa 7S 
QO drs 
823 0.75 


An encode function may also be specified for vectors and multi- 
dimensional arrays. The shape of the result of the function R<«ATB is 
always (pA).,9B or the same as the outer product. Examples of encoded 
arrays are included below. 


Neeens 22 3 


“y 
x 


] 
+ 


2 2 3 
eBeart 2 
1 90 
i 0 
1 0 
2 2 
£ 2 
a 2 
Pr t& 
2 32 
eCee 2P B65 429 103 492 
865 429 
103° 692 
19 10 Lore 
eg 4 
L oS 
& 2 
oO 9 
ua 
3 2 
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2.7.23 4: Decoding a Number Representation 


Function: dyadic decode (1); R+«XiY 
Argument Domain: 

left: numbers 

right: numbers 
Argument Shape: 

left: @ny 


right: any 
Result Range: numbers 
Result Shape: array 
Origin-Dependent? no 
Take Dimension Argument? no 





The dyadic decode (1) function reduces a representation in a number 
system to a value. It is the converse of the encode function (Section 
2.7.19) and is sometimes called the base value function. | Equivalent 
examples of the two functions as they operate on a quantity expressed 
in yards, feet, and inches are shown below. 


L760 8 dora 
1 2.38 

1760 $3 12.1 2 3 
OS 


The functions ATB and AiB differ only in the values included as B; A 
expresses the number base in both cases. 


The number of elements in A and B must generally be the same; element 
2 in A expresses the base in which element 2 in B is encoded, and so 
on. However, if A is a scalar or a single-element array, it is 
extended so that its length is the same as that of B. For example, 
the following function has the effect of producing the base 10 value 
of the base 8 number 3777. 
8413 7 7 7 
2047 
The decode function may be viewed as a form of inner Product. The 
following illustrates two equivalent functions. 
Me 1760 % 12 
Bel 2 3 
wed 
&3 
$6 L2 Le xe 
G3 
The following are several additional decode examples: 


eal O10 


Lo 
Bil 4 4 
100 
“Sat £ -O 16 
“y 
L424 211212 1 
L099 


(number of pints in bushel, 2 
pecks, 1 gallon, 2 quarts, 1 pint) 
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A decode function may also be specified for multi-dimensional arrays. 
The function A1B is equal to W+.xB where W is the weighting vector 
given by W[pA]<«>1 and WL(-N)+pA]<>AL(-N)+1+pA]xWL(-N)+1+p4]. The value 
of Afi] is thus irrelevant. 


The arrays specified as the arguments of the decode function must con- 
form according to the rules specified for inner products in Section 
2.8.3. As with the inner product function, if neither decode argument 
is a scalar, then the number of elements in the last coordinate of the 
left argument must equal the number of elements in the first coordi- 
nate of the right argument, or either of these coordinates must con- 


tain exactly one element. In general, if the left argument (A) is a 
vector and B is the right argument, then the result is W+.xB where 
WLI]+x/I+A. If A is a scalar or a vector of equal elements, the 


result is the decimal value of the right argument in base A. 


Several examples of decode functions that use arrays are provided 
below. 


(eens 2F2 3 


= 2 2 
os § 3 
ewes QF oO O 1 1 90 
1 0 
oO dl 
1 0 
Ory Ks 
w 2 
10°) 63 
ewe? Be4 219 Sd 
4 2 1 
? 3 | 
Ways MUS 
3 2 
10.) 63 
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2.7.24 ¢: Executing a Character String 


Function: monadic execute (¢€); R+«eY 
Argument Domain: 

left: - 

right: Characters 
Argument Shape: 


left: — 

right: vector 
Result Range: characters or numbers 
Result Shape: scalar or array 
Origin-Dependent? no 
Take Dimension Argument? no 





The monadic execute or unquote («) function is used to execute a char- 
acter string as an APL statement. The scalar or vector included as 
the right argument of the function is evaluated as a character string 
to be executed by APL. An example of this function is shown below. 


[Jee ge | DWARF 
&y & [iss qh x K ™ mM tp i 


The effect of this example is to execute the )VARS system command 
(see Section 5.3.1) and thus obtain a display of the global variables 
available in the user's workspace. 


The right argument of the « function may be a scalar or a character 
vector. If the scalar value A is numeric, then the value of <A is 
equivalent to A. If A is a character scalar or vector, it is 

evaluated exactly as if it were quad input from the terminal. Carriage 
return/line feed characters in A are treated as APL statement separa- 
tors, just as they would be in input from the terminal, so multiple 
line executes are allowed. The result of the expression R+eA is the 
value of the last statement evaluated in 4. If the last statement has 
no value (e.g., R+e''), R is the null vector. 


Errors encountered in the character string processed by the execute 
function are handled exactly as if they occurred in statements entered 
from the terminal. If an error is encountered while evaluating the 
execute string, an error message is output and the segment of the 
execute string currently being evaluated is displayed. (Output may be 
Suppressed by it-beam 16, described in Section 4.3.2.) If an error 
occurs, no further evaluation of the string is performed, and «A 
returns a null array whose shape is 0 F, where F is a number indicat- 
ing the error that was encountered. Appendix D contains a complete 
description of all APL error conditions. 


The execute function is also known as the unquote function, because 
it strips quotes from the value entered as its argument. Other uses 
of this function besides the execution of system commands include the 
following: 


e Function definition (line editing commands are not 
permitted) 
e Conversion of vectors of characters representing numeric 


constants into numeric values 


e Specification of an APL name as an argument to a function, 
rather than the value of that name 
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The examples included below illustrate the use of e« in function 
definition, the execution of system commands, and the evaluation of 
APL statements. 
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2.7.25 ¢€: Determining the Members of an Array 


Function: dyadic membership (¢€); R+«XeY 
Argument Domain: 

left: any 

right: any 
Argument Shape: 


left: any 

right: any 
Result Range: Booleans (0,1) 
Result Shape: array; pR+pY 
Origin-Dependent? no 
Take Dimension Argument? no 





The dyadic membership («) function is a set function that is used to 
determine whether or not particular elements of one array occur as 
elements of another array. Both arguments of the function 4eB may be 
arrays of any dimension; the left argument, A, contains the elements 
for which membership in array B is to be determined. The result of 
the membership function is a boolean array whose shape is the same as 
that of A. The result consists only of 0's and 1's; a 1 indicates 
that the corresponding element in A is a member of array B, a 0 that 
it is not. Following is an example of the use of the « function in 
analyzing the membership of a vector. 


[]e Og ECC CUE Gh! og) TRE AE 


10011096 


Af) CE 






AEH 


The compression function is helpful here in identifying the particu- 
lar characters that are members of the vector. 


The two arguments of the membership function need not have the same 
rank, as is illustrated in the first example below. 


Ae BY 8 2 4 & & 
Be i} 
oO OD 4 
ho of od 
3oo4e AQ! 
oO 0 
3 4210 
Oo oO 


For all arrays B, the expression 4cB is equivalent to Ae,B. 
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2.7.26 u: Eliminating Duplicate Elements in a Set 


Function: monadic elimination (vu); R«uY 
Argument Domain: 

left: - 

right: any 
Argument Shape: 


left: ~ 
right: Any 
Result Range: Characters or numbers 
Result Shape: vector 
Origin-Dependent? no 
Take Dimension Argument? no 





The monadic elimination (uv) function is a set function that eliminates 
the duplicate elements in a single set. The argument of the function 

vA may be a numeric or character scalar or an array of any dimension. 

The result of the function is always a vector, regardless of the shape 
of the argument, A. The result vector contains only one occurrence of 
each argument element, even if it occurs multiple times in A. 


ul © 181 0 1 @ 
1 0 

UA SE 
LeVS BLE 

uid 
L283 4 5 4 
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2.7.27 vu: Determining the Union of Two Sets 


Function: dyadic union (u); R+«XuY 
Argument Domain: 

left: any* 

right; any* 
Argument Shape: 


left: any 
right: any 
Result Range: Characters or numbers 
Result Shape: vector 
Origin-Dependent? no 
Take Dimension Argument? no 





The dyadic union (u) function is a set function that concatenates 
two arguments and creates a vector consisting of the elements 

of the arguments. The arguments of the function AuB may be 
scalars or arrays of any dimension. The result of the function is 
always a vector, regardless of the shape of the argument. The 
arguments may be either numeric or character, but both arguments 
must be the same type or a DOMAIN ERROR will result. 


In the union example below, note that duplicate elements from the 
concatenation of the two arguments are not discarded: 


"BARNYARD'u 'YARDARM' 
BARNYARDYARDARM 


The following examples illustrate the use of the union function with 
a variety of arguments of different shapes. The final example illus- 


trates that the shape of the result is always a vector, even if it 
consists of a single element. 


Los 3u4 


aug dd 





AUF 
2342345 6 

ah a ne a a 2 gem 
RUVESLELE 

Paty! + 





*Both arguments must be either character or numeric; argument 
types cannot be mixed in the same function. 
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2.7.28 nz: Determining the Intersection of Two Sets 


Function: dyadic intersection (nN); R+«xXnY 
Argument Domain: 

left: any* 

right: 2ny* 
Argument Shape: 


left: any 
right: any 
Result Range: characters or numbers 
Result Shape: vector 
Origin-Dependent? oO 
Take Dimension Argument? no 





The dyadic intersection (n) function is a set function that determines 
the elements that the two arguments of the function have in common. 
Both arguments of the function AnB may be scalars or arrays of any 
dimension. The function returns the elements of the left argument, 
A, that are also in the right argument, B. The arguments may be 
either numeric or character, but must both be the same type. The 
result of the function is always a vector, regardless of the shape 
of the argument. 


Note that multiple occurrences of an element in the left argument that 
also are present in the right argument will appear an equal number of 
times in the results. This is illustrated in the second example. 


19 20 B3On10 3Q SO 7 


LQ 30 


PRED S GOURD yp UM IEE ra ee nt 


MISSI 
Cidsinrve 
125 45 6 
ye 
L oO 2d 6 


*Both arguments must be either character or numeric; argument 
types cannot be mixed in the same function. 
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2.7.29 ~: Excluding Set Elements 


Function: dyadic exclusion (~); R«X~Y 
Argument Domain: 

left: any* 

right: any* 
Argument Shape: 


left: any 
right: any 
Result Range: characters or numbers 
Result Shape: vector 
Origin-Dependent? no 
Take Dimension Argument? no. 





The Qyadic exclusion (~) function is a set function that returns 

the elements that are in the first argument of the function, but not 
in the second. Both arguments may be scalars or arrays of any dimen- 
sion. In the function A~B, the result is a vector consisting of the 
elements in the left argument, A, that are not also in the right 
argument, B. The arguments may be either numeric or character, but 
must both be the same type. The function is always a vector regardless 
of the shape of the argument. 


‘MIS GES S IEE Dw (OMS SOUT 


Note that the exclusion function returns the elements in 'MISSISSIPPTI' 
that are not in 'MISSOURI', but it does not return the elements in 
"MISSOURI' that are not in 'MISSISSIPPI'. APL effectively crosses 
Out the elements in the left argument that are also in the right 
argument. The set of elements that remain in the left argument is 

the result of the function. 


When the left argument is null, the function returns the null vector, 
as shown in the second example below. 


A DUV EEL ELE hae t 3 
Wed TE SS EL RE 


tn  SHVIGIELE ! 


*Both arguments must be either character or humeric; argument 
types cannot be mixed in the same function. 


THE APL LANGUAGE 


2.7.30 c¢: Determining a Proper Subset 


Function: dyadic subset (¢c); R<XcY 
Argument Domain: 

left; any* 

right: any* 
Argument Shape: 

left: any 


right: any 
Result Range: Booleans (0,1) 
Resuit Shape: 1-element vector 
Origin-Dependent? no 
Take Dimension Argument? no 





The dyadic subset (c) function is a set function that determines 
whether or not the left argument is a subset of the right argument. 
Both arguments may be scalars or arrays of any dimension, The argu- 
ments may be either numeric or character, but must both be the same 


type. 


In the function AcB, APL determines whether or not all of the elements 
of the left argument A, are contained in the right argument, B. The 
result of the subset function is always a single-digit boolean vector 
(0 or 1), regardless of the shape of the arguments. A value of 1 
indicates that A is a proper subset of B; a value of 0 indicates that 
A is not a subset of B. Several examples of the subset functions are 
included below. 


"MISS'c'MISSOURI' 


1 
0121201 3 
1 
0 1c10 2 0 
0 
'BLISS'c'INVISIBLE' 
1 
Every occurrence of a distinct element in the left argument must be 
matched by an occurrence in the right argument. In the last example 
above, 1 is returned even though the letter S occurs twice in 'BLISS' 
and only once in 'INVISIBLE'. A match need not be found for every 
occurrence of an element in the left argument; thus, "SS" in "BLISS" 


will be matched by "S" in "INVISIBLE". 


The subset function can be expressed in terms of the and, compression, 
ravel, and membership functions as the following: AcB++A/AceB. 


2.7.30.1 ¢: Determining a Subset - The description for a subset (c) 


is the same as for a proper subset (c), except that now a true 
result (1) is returned if the arguments contain the same elements. 


Q 


*Both arguments must be either character or numeric; argument 


types cannot be mixed in the same function. 
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2.7.31 >: Determining a Strict Superset 


Function: dyadic superset (2); R«*xX>Y 
Argument Domain: 

left: any* 

right: any* 
Argument Shape: 


left: any 

right: any 
Result Range: Booleans (0,1) 
Result Shape: 1-element vector 
Origin-Dependent? no 
Take Dimension Argument? no 





The dyadic superset (>) function is a set function that determines 
whether or not the left argument is a strict superset of the right 
argument. It is the converse of the subset function described in 
Section 2.7.30. Both arguments in the superset function may be 
scalars or arrays of any dimension. The arguments may be either 
numeric or character, but must both be the same type. 


In the function A>B, APL determines whether or not the left argument, 
A, contains all of the elements of the right argument, B. As with 
the subset function, the result of the Superset function is always 

a single-digit boolean vector (0 or 1), regardless of the shape of 
the arguments A value of 1 indicates that A is a superset of B; a 
value of 0 indicates that A is not a superset of B. 


In the superset function, every occurrence of a distinct element in 
the right argument must be matched by an occurrence in the left 
argument; this is illustrated in the examples below. 


(19) 21 3S 7 9 wi 
0 


ap 

IMIS SOUR T ty tM ESS! 
i 

CiS)el 2 3 4 5 
0 


The superset function can be expressed in terms of the and, compres- 
sion, ravel, and membership functions as the following: A/,BeA. 


2.7.31.1 >: Determing a Superset ~ The description for a superset 
(2) is the same as for a strict superset (5), except that now a true 
result (1) is returned if the arguments contain the same elements. 


9) 


*Both arguments must be either character or numeric; argument 
types cannot be mixed in the same function. 
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2.7,32 %: Formatting an Array 


Function: Monadic format (%); R<tY 
Argument Domain: 

left: —- 

right: any 
Argument Shape: 


left: ~ 

right: any 
Result Range: Characters 
Result Shape: 2° Tay 
Origin-Dependent? no 
Take Dimension Argument? no 





The monadic format (t) function is used to convert numeric arrays to 
character arrays. Whereas the right argument of the dyadic form of 
this function (Section 2.7.33) may only be a numerical array, the 
right argument of the monadic version may be a scalar or an array of 
any shape, and the value of the argument may be numeric or character. 
The symbol + is formed by overstriking the job character (ec) with the 
symbol T. 


When applied to a scalar or a character array, the result of the 
format function R+t4 is an array identical to A - for example: 


¥') VARS' 
) VARS 


If A is a numeric, then the character array represented by RF will be 
identical to A as it appears when displayed by APL, However, the 
blank characters displayed along with the values of A will actually 
be a part of the new array R, The format of a scalar number is 
always a vector. The following example illustrates the difference 
between the shapes of a displayed numeric array and a formatted 
character array. 


He? 4P 18 
Bh ye ED 
# 


Lt 2 3 4 
S 6 F & 
ion 
> 4 
& 
1 2 3 4 
5 6 FF 8 
f kK 
dA, 
BLE 14+ 3x a 
1234 
S673 
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2.7.33 %: Formatting a Character Array with Width and Precision 


Function: dyadic format (¥); R+XtY 
Argument Domain: 

left: integers 

right: numbers 
Argument Shape: 


left: scalar or vector 
right: any 
Result Range: characters 
Result Shape: array 
Origin-Dependent? no 
Take Dimension Argument? no 





The dyadic format (+) function is used when control of output exceed- 
ing that available with the monadic format is required by the user. 

It offers a number of formatting options but does not provide the 
comprehensive formatting capabilities available with the format (7) 
function described in 2.7.32. The right argument of the dyadic format 
function may only be a numeric array. The left argument is used to 
control the format of the result. This argument may be a scalar, a 
pair of numbers, or a vector whose length is twice the number of 
columns in the numerical array. 


Two numbers are normally supplied as the left argument of the format 
function. The first specifies the width of a numeric field and the 
second sets the precision of that field. Precision is expressed 
differently for decimal and scaled or exponential forms of output. 
The form is determined by the sign of the precision argument. For 
decimal output, precision is a positive number, expressed as the 
number of digits to the right of the decimal point. For scaled out- 
put, precision is negative and is considered the number of digits in 
the multiplier. Following are several examples of output using 
different width and precision specifications. 


Mw 
te 





31.16 0 OF OO 
“PLS,878 8 “2 a5.) 
aed 
woe 
Lie Te 1 Bee 
41.160 0,000 “42070 
“LS. 378 3.000 285.410 
eT 
2 46 
AGG Dex 
rs) 
31.16 0.00 “LsO? 
“15.58 8,00 “235.41 
Pe 
2 2? 
Fide Chapt 
Fy 
a1 18) mei) 
16 8 “236 


i 
3, 1EO] O.,OFOG “1. LEQO 
“1.6E01 8.0E00 ~2,4E02 
ecez “19s 
SEOL OFOO ~LEOO 
“BEOL BEOO “BEO2 
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If the width specification is zero or is omitted from the function, 
APL provides a default width such that at least one space is inserted 
between pairs of numbers. If only one number is provided as the left 
argument of the function, the number is assumed to represent the pre- 
cision of the result, not its width. An example is shown below, 
using array X¥ as presented above. 


Pile Qe 
31.16 0.00 “1,07 
“15.58 8.00 “235.61 


2 20 


The user may also specify width and precision arguments for each 
column of the array to be formatted. Following is an example of 
column formatting of array X. 


Fle8 O 0 "2 8 OF 
31 0,0E00 “it 
“16 8,0E00 “236 


om a ind 


A format function may also be specified for a multi-dimensional array 
and applied to the last coordinate - for example: 


TeAee? 2 2P1B 


be 
br 


ee a) 
1.00 2.00 
3.00 4.00 


3400 6.00 
7490 8400 


In general, the width specified by the user must be large enough to 

jaccommodate the number field. However, APL does not require that 

space be inserted between columns, as is illustrated by the following 
a logical array. 


1 @ 
ct @ J 
I 1 1 
1 Or 
100 
101 
Lad 


The dyadic format function provides a powerful facility for formatting 
tables and providing headings and labels. Following is an example 
of a table prepared using the format function. 
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ROWSE S 7p AFL FORTRORCOBOL EASIC FLI . 
COLSe¢ ! USERS FROGS SYSTS' 
FORME Bra 
(' 'yCLJROWS),COLS sf 137 OrFORM 
USERS FROGS STSTS 
AFL 112 608 14 
FORTRAH 306 58S 26 
COBOL 596 B21 45 
BASIC 622 960 30 
PLI 18 35 3 


Note that array A contains the data formatted for inclusion in the 
table. 
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2.7.34 H: Performing Matrix Inversion 


Function: monadic domino (fH); R+aY 
Argument Domain: 

left: — 

right: numbers 
Argument Shape: 

left: - 


right: scalar or array; (ppY)<S2 
Result Range: numbers 
Result Shape: array; op R+>p Y 
Origin-Dependent? no 
Take Dimension Argument? no 





The monadic domino (ff) function inverts a matrix and thus facilitates 
matrix division and a variety of other matrix operations. The domino 
symbol, &, is formed by overstriking the quad (0) character with the 
division (+) symbol. The right argument may be a scalar, a vector, or 
a matrix. The most useful applications of the domino function include 
the following: 


® finding the inverse of a matrix 
® solving sets of linear equations 


6 determining a least squares solution to an overdetermined 
set of linear equations 


Only the first application is discussed in this section. The dyadic 
version of the function is described in Section 2.7.28 and is used in 
performing more sophisticated matrix operations. The monadic inver- 
sion function operates as shown below. 


& 
"5 2 
—g 
He 
4 OS 
3075 
Hex eg 
9 “36 30 


“36 192 “180 
360° “180 180 

CS a as 
1,000000000 “7 1OS427358E71S5 6.661338148E715 
3+ 3S0669074E"146 1,.000000000 2+442490654E7-15 
2677555756227 16 “1,.554312234E7-15 1.000000000 
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The monadic expression fx is equivalent to the dyadic Ix, where rf is 
an identity matrix whose order can be described as itpx. If the argu- 
ment of the monadic function is a scalar, the expression HX is equiva- 
lent to :X. 


The argument of the matrix inversion function may be non-square, but 
the matrix must have at least as many rows as columns. In a non-square 
situation, the result is a left inverse of the argument. If the matrix 
has no inverse, a DOMAIN ERROR results. 
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2.7.35 &: Performing Matrix Division 





Function: dyadic domino (Hf); R+«XHY 
Argument Domain: 

left: numbers 

tight: Numbers 
Argument Shape: 

left: Scalar or array; (ppY)<2 


tight: scalar or array; (ppY)<2 
Result Range: numbers 
Result Shape: array 
Origin-Dependent? no 
Take Dimension Argument? no 














The dyadic domino (f) function performs more complicated matrix opera- 
tions than the inversions described in Section 2.7.34 - for example, 
solving linear equations and finding a least squares solution. Both 
arguments of the # function may be scalars, vectors, or matrices. In 
the expression XHY, X and Y must conform, fulfilling all of the condi- 
tions described below. 




















1. Y must have a rank of 2 or less. 
2. If the dimensions of Y are M by W, then M2. 
3. X must have a rank of 2 or less and (l1tpY) = ltpxX. 


This implies that for matrices, X¥ and Y have the same number of rows 
and the columns of Y are linearly independent. If Z+XHY, then 
ppZ+soppX and +/((Y+.xZ)-X)*2 is minimized. 


The following example illustrates the use of the matrix division 
function in solving a set of linear equations. The equations are: 


ROLE om F 
Aw Eo ocx 











In expression XY, Y is a matrix whose values are the coefficients of 
the equations, and X¥ is a vector containing the values 9 1. 


HED d 
Ye? QP3 1 2 “1 
MET 

2 3 


The result is a vector in which the first element is the value of A 
in the linear equation, and the second is the value of 8. 


The domino function treats scalar arguments as matrices containing 

one row and one column. The expression XHY is equivalent to scalar 
division X+Y, except that the operation 0&0 produces an error 
condition. If the arguments are vectors, they are treated as matrices 
with a single column. As mentioned in Section 2.7.35, if I is an 
identify matrix of the same dimension as X, then &X is equivalent to 
TX. 




















A more general statement of the relationship between the monadic and 
dyadic forms of the domino function is the following. The expression 
Hx, where X is a matrix, is equivalent to ((1¥)°.=1¥)HX, where Y is 
the number of rows in X. 
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Following are several examples of the use of the dyadic domino func- 
tion, including a least squares solution. 


HeAe (2? Lr2 del 


2 1 
3 1 
Feld 19 
pre kya 
2 
Op, Ks 
10 19 
Hee ch LPS o1 
4 od 
2 1 
3 4d 
4 1 
oS ot 


BE9,001 2.998 4.002 4.997 6.0) 
le xeegya 
1.0017 0.9965 
Fen by 
2+BO000002Z9E"S “Le. B9999IF4H7ZE-3 4,00000077E~4 “Gs 299999899E-3 
5. 0000001 25E73 
Klee Ae 
“LePF99SSSISE™- 1 “1, 000000023EF 7 1 
Le PO9S99GPFE 1 
O67 99999994 0.500000008 Z+QOO000002Z0E "1 “1, 000000043E™ 1 
“SZ G9PG99PGPFE 1 


b 


+SS7563222E710 1,000000032E™1 


Me, xXa 
14900000000 +P 38B9IS9O4E “18 
“A 163336342E717 1,000000000 
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2.8 OPERATORS 


The operators described in this section are APL functions that take 
primitive scalar functions such as + or x as their arguments. 
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2.8.1 f/: Reducing an Array 


Funetion: monadic reduction (f/); R<f/(K]Y 
Argument Domain: 

left: - 

right: same as for function f 
Argument Shape: 

left: ~~ 


right: vector or array 
Result Range: Same as for function f 
Result Shape: array (ppR)+>or |+ppY 
Origin-Dependent? no 
Take Dimension Argument? yes 





The monadic reduction (f/) operator combines the elements of a vector 
or the elements along a specified dimension of an array. 


The following example illustrates the use of reduction in obtaining a 
sum, product, maximum, and minimum value for vector X. 


exe 1} 
12345 4 


+ ft 
2 

KAM 
Fa 

ps 
é 

L/x 
1 


The general requirement for reduction is that the function (f) to the 
left of the reduction symbol (/) be a scalar dyadic function (see 
Section 2.6). If f/V represents a reduction, then an equivalent form 
is the following: 


VILISVI2If..-fVIeVI 


where the expression is evaluated from right to left in the conven- 
tional way. The result of reducing any vector is a scalar value. 

If V is a scalar or a vector with a single element, then f/V<>V. If 
V is an empty vector, then the result of a reduction is the identity 
element of the function, if one exists - for example: 


+#/35 7 8 
20 

~/1 6 7? 
ed 

t/? 
7 

X/10 


1 


Table 2-6 summarizes the identity elements for the primitive scalar 
dyadic functions presented in Section 2.6 that may be returned by the 
reduction function. 
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Table 2-6 
Identity Elements of Scalar Dyadic Functions 


Dyadic Identity 
Function Element 


Plus 
Minus 
Times 
Divide 
Power 
Residue 
Maximum 
Minimum 
Logarithm 
Out of 
Circle 
And 

Or 

Nand 

Nor 

Less 

Not greater 
Equal 
Greater or equal 
Greater 
Not equal 


~1.70141F4+38 
1.70141E+38 
None 
al 
None 
al 
0 
None 
None 


+ 
x 
* 
| 
r 
L 
® 
t 
fe} 
A 
v 
n 
bd 
< 
< 
Fs 
> 
Z 





A reduction operation may also be specified for one particular 
coordinate of a multi-dimensional array by including the coordinate 
number in brackets. The result of reducing an array has a rank that 
is one less than the rank of the original array. Thus the reduction 
of a matrix yields a vector, as shown in the examples below. Note 
that +/[1]A operates on the first dimension of A and produces a column 
sum; +/[2]4 operates on the second dimension and produces a row sum. 


The following examples also illustrate the defaults which APL supplies 
when the coordinate number is omitted from the function. 


Te Oe? 4F 16 
1 2 3 4 
4 6 1 2 
4/2 7A 
10 14 
e/a 
6 8 4 6 
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2.8.2 f\: Scanning an Array 


Function:monadic scan (f\); R«f\[KIY 
Argument Domain: 

left: - 

right! same as for function f 
Argument Shape: 


left: - 

tight: vector or array 
Result Range: same as for function f 
Result Shape: array; pRh<>pY 
Origin-Dependent? no 
Take Dimension Argument? yes 





The monadic scan (f\) operator is used to derive partial results in 
calculating the reduction of an array. For example, if V is a vector, 
the expression +\V produces a vector of the partial sums of V. An 
example of this is shown below. 


t\3 4 5 
3 7 12 


Here each element of the resulting vector can be considered a reduc- 
tion of the original vector up to that point. In the resulting 
vector, the first element is always identical to the first element of 
the original vector, and the last element is equivalant to a reduction 
of the entire original vector. 


The general requirement for the scan is that the function (jf) to the 
left of the scan symbol (\) be a scalar dyadic function (see Section 
2.6). Following are several other examples of the use of the scan 
function. 


X\2 2 23 
2 4 8 
vO 19 9 
oO 1 iol 
XN\L? 
24 120 720 5040 
2N8 


1 


ho 
RB 


8 


If f\V represents a scan of a vector, then the scan of any given ele- 
ment in terms of reduction is the following. 


R(K] = f/Ktv 


The shape of the result of a scan is the same as the shape of the 
original vector (pR=pV). If the right argument of the scan is a 
scalar or a vector with a single element, then f\V<+V. If V is an 
empty vector, then the result of a scan is the empty vector. 


A scan operation may also be specified for one particular coordinate 
of a multi-dimensional array by including the coordinate number in 
brackets. Several examples of scan functions are included below. 
These examples also illustrate the defaults which APL supplies when 
the coordinate number is omitted from the function. 
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eA? BRIG 


i 2 $3 
4 § 6 
#t\E 14 
i2 8 
& 7 
t\ 02748 
1 3 & 
4 g 15 
+\A 
1 3 & 
4 9 15 
+h) 
i 2 #3 
my oP OY 


If the dyadic function being performed by a scan is associative (e.g., 
+, x), APL performs the scan in a way that is different from the con- 
ventional scan in order to increase efficiency by reducing the number 
of operations performed. The definition of R+f\A in this case is 
equivalent to R[IJ=f/I+A as follows: 


R[1)]=4[1] 
R(IJ=R[I-1]fA[I] for Tel+ipA 


This definition requires fewer operations than the traditional scan. 
It is possible that the result of an associative function of this 
kind may differ slightly from the non-associative approach and should 
be used carefully if the results require a high degree of precision - 
for example 


ALES “JEG LETTS 
$\A 

LOOOO0D O O 
+ /F 

1) 
+/ 4 

LET16 


2 
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2.8.3 f.g: Computing the Inner Product of an Array 


Function: dyadic inner product (f-gq); 
Argument Domain: &A<Xf-gY 

left: same as for functions f and g 

right: Same as for functions f and g 
Argument Shape: 

left: any 


right; any 
Result Range: same as for_functions f and g 
Result Shape: array pR<«>( | ipX),] +pY 
Origin-Dependent? no 
Take Dimension Argument? no 





The dyadic inner product (f.g) operator returns the common algebraic 
matrix product and also extends this capability to other arithmetic 
operations and other array dimensions. The following example illus- 
trates the use of the inner product function in calculating a matrix 
product. 


Meee? SrrvS 
i 2 3 
4 3 6 
[Je Be 1 3 
L 2 3 
fie, XE 
14 32 


Here the corresponding elements of B and each row of A are multiplied 
(g function) and then summed (f function). Thus (1x1) + (2x2) + 
(3x3) = 14 and (1x4) + (2x5) + (3x6) = 32. 


The inner product operation is expressed as R<«Af.gB, and functions 
f and g may be any dyadic scalar functions (see Section 2.6). 


In APL, this matrix product capability is generalized and may be 
expressed in terms of reduction. If A and B are both vectors, then 
the result is a scalar as shown below. 


Cisd+.xi1g 
14 


The expression R+A+.xB in this case yields the scalar +/AxB. If A 

is a vector, B is a matrix, and I and J are element indices, then 

R is a vector in which R[J] is equivalent to +A/xB[;J]. If A isa 
matrix and B is a vector, as illustrated in the first example in 

this section, then F is a vector and R[I] equals +/A[I;]xB. If A 

and B are matrices, then R is a matrix and R[I;J]+-f/AlIslgBlid]. 
Following are several examples of inner product functions with differ- 
ent argument dimensions. Note that the last two examples illustrate 
alternative solutions to the same problem. 


Melle? BG 
3 
é 

Ae. XU 


> 
th fo 


2 6t,44 
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At + xRA 
14 32 
32 77 

CUB +e xis 
14 

t/C1 2 Bae 
14 


It is often very useful to specify an inner product operation in 
which an operation other than ordinary multiplication is performed. 
It is possible to locate values containing specific characters by 
this method or to search for a row of one array in which all the 
elements are equal to those in a column of another array. The follow- 
ing example returns a logical vector in which 1 indicates that the text 
string SIX has been located in the corresponding row of array X. 
ORE 
TWO 
6 TM 
TEM 
pH 
4 3 
Te! SIH! 
pT 
3 
Sat yee 


Oo 0 1 6 


In general, A and B may be scalars or any arrays. If either argument 
is a scalar or a l-element vector, it is extended so that its length 
matches the length along the first (last) dimension of the other 
argument. The result of an inner product function has dimensions 
such that pf is equal to (pA).,pB, except for the last dimension of 

A and the first dimension of B(the two inner dimensions); these can 
be expressed as 1+tpA and itpB, and the shape of the result is 
pR<+>(~1+pA),149B. (See the take and drop functions, Sections 2.7.11 
and 2.7.12) If pA<+-M W and pB<+-L, then L=N and pR=M. 


A and B must conform in order to be used in an inner product 
operation. A and B conform if any of the following characteristics 
is true: 


ls A or B is a scalar. 
2. The results of “1tpA and itpB are equal. 
3. Either “itpA or itpB equals 1. 


If the third characteristic is true, then the corresponding argument 
is extended so that the arguments have equal lengths along the 
specified coordinate. The basic test for conformability is whether 
or not the last dimension of the left argument matches the length 

of the first dimension of the right argument. The dimensions of 

the result can then be considered all except the last dimension of 
A, catenated to all except the first dimension of B. Table 2-7 may 
be helpful in determining the conformability of two arrays. 
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Table 2-7 
Inner Product Definitions 


Conformability Definition 
pA pAf.gB Requirements Z+Af.gB 


Z<«f/AgB 
Z+F/AgB 
Z+f/AgGB 


2+f/AgB 
Z0II1+f/AgBL 37] 
ZLII<f/ACI3;1gB 
ZUIIN<+f/AgBL sr] 
ZUII+f/ACI31gB 
ZLIsJI<f/AlI31gBl 37] 





2.8.4 o.f: Computing the Outer Product of Two Arrays 


Function: dyadic outer product (°.g); R«Xo.gY 
Argument Domain: 
left; Same as for function g 


right: Same as for function g 
Argument Shape: 
left: any 


right: any 
Result Range: same as for function g 
Result Shape: array; pR«>(pY), pX 
Origin-Dependent? no 
Take Dimension Argument? no 





The dyadic outer product (°.g) operator specifies an operation to 
be performed between every element of one array and every element 
of another array. The form of the function can be expressed as 
R+Ao.gB, where A and B are any arrays and g is any dyadic scalar 
function (see Section 2.6). Note that the ° symbol is the jot 
character (upper-case J on APL terminals). fF is an array that 
results from applying g to every pair of elements of A and B. The 
shape of FR is the dimensions of A catenated to the dimensions of 
B, or (pA),pB. The following example illustrates the use of this 
function when A and B are both vectors. 


1 2 3e,x3 3 4 5 

4 be] 
8 10 
12 


1S 


2 3 
4 & 
& 9 


Unlike the inner product operator, the outer product performs only 
one operation - in this case, multiplication. The resulting array 
is a matrix with three rows (pA) and four columns (9B). It is 
formed by multiplying each element of A by each element of B in 
turn - for example, 1x2=2, 1x3=3, 1x4=4, 1x5=5 for the first row, 
2x2=4, 2x3=6, 2x4=8, 2x5=10 for the second row, and so on. The 
example included below illustrates the use of the outer product 
operator in searching for the occurrence of particular numbers. 
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Atl 23 22 3 


an 


C13) e,sA 


1 Oo 0 0 QO 9 
oO 1 0 1 1 86 
Oo 9 1 0 0 Ff 
t/ OY Reg 
1 3 2 


If A is a vector and B is a matrix, then the result of R+Ao.fB 
contains R(I;J;K] <+ ALIIFBLI;K]. 


Table 2-8 may be helpful in determining the definition of a variety 
of outer product results. 


Table 2-8 
Outer Product Definitions 


Definition 
Z2+A°.gB 


Z+AgGB 

ZLIIJ<AgB(T] 

ZC II1<ACIIgB 
ZLI;J]+AlLIIgBl7] 
ZLI3J1+AgBlI3J] 
Z(I;J1«LIsJ]gB 

Z0I3J;KI<CIIlgBlJ;3K]} 
ZO0I3sJ3KI<+CI;sJI]gBlK] 
ZLIsJ3K3;LI<ALI3;J1gB(K3L) 


E 
D 
D 
E 
C 
D 
C 
C 


E 
V 
D 
E 
D 
D 
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CHAPTER 3 


DEFINING AND EXECUTING APL PROGRAMS 


3.1 MODES OF OPERATION 
APL language statements operate in either of two modes: 


e@ Immedtate or executton mode: in this desk-calculator mode, APL 
statements and expressions entered by the user are executed 
immediately. 


e@ Funetton-definitton mode: in this mode, APL programs and func- 
tions are developed, edited, named, and saved for use at a 
future time. 


The APL user can shift conveniently from one mode to the other by 
typing a mode-transfer "del" (V) symbol. The mode in which APL state- 
ments are to be executed does not affect the syntax of language state- 
ments and expressions. However, there are a few special APL characters 
available for use in function-definition mode and a variety of practi- 
cal considerations to be taken into account when constructing a func- 
tion to be executed at some future time. This chapter discusses the 
use of function-definition mode in detail. It focuses on: 


e Function definitions, headers, and variables 
e Editing procedures for revision and line-editing modes 


e Branching and the use of labels, trace vectors, stop vectors, 
and the state indicator 


e Use of locked and suspended functions 


3.2 DEFINING THE FUNCTION 


APL provides a comprehensive facility for defining, changing, and in- 
voking user functions that supplement the large set of primitive func- 
tions that exist in the language. Once the user has developed or re- 
written a program in APL function-definition mode, that program may be 
used with the convenience of a primitive function. 


A defined program or function is constructed in two parts: a function 
header and a function body. The funetton header defines the name of 
the program or function and the syntax of the function call. The func- 
tton body consists of a number of program statements that define the 
actions to be performed by the function when it is executed. The user 
enters function-definition mode by specifying a del character (V), fol- 
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lowed by the function header and a carriage return. This signals the 
APL processor not to execute subsequent lines as they are entered, as 
it would in immediate mode. 


In function-definition mode, APL prompts the user for successive state~ 
ments of the function body by displaying successive bracketed line num- 
bers for every line. Lines entered by the user are treated as function 
lines until APZ encounters another V character, which signals a return 

to immediate mode. The format of a function definition is shown in the 
following: 


Vv funetton header 


[1]. 
E2] 
[3] *% 
[4] funetton body 
[5]. 
[6] . 
{7] . 
(s] Vv 


There are no restrictions on the type of statements that can be in- 
cluded in a function definition. System commands may be included in a 
definition, and function definition and execution are permitted in quad 
input mode (Section 2.5.1). In this case, the input request remains 
pending until the user returns from function-definition mode to im- 
mediate mode. 


3.2.1 The Function Header 


The function header specifies the name of the function and the syntax 
of its call. There are six distinct types of functions; a function 
may have zero, one, or two arguments and the function may or may not 
return a result value. If a defined function has an explicit result 
value associated with it, this value must be assigned during execution 
of the function. Defined functions that return results may occur in 
expressions; those that do not return explicit results must appear 
alone in statements or be the last function to be executed in an APL 
statement line. 


Defined functions may be classified as: 
@ niladic (no arguments) 
@® monadic (one argument) 
e dyadic (two arguments) 


Examples of function headers in these three categories are included 
below. Note that each type may or may not return a result value (2). 


Type Explicit Result No Explicit Result 
Niladic V Z<FNAME V FNAME 
Monadic VY Z+FNAME ARG V FNAME ARG 
Dyadic V Z+LARG FNAME RARG VY LARG FNAME BARG 


Sample niladic, monadic, and dyadic functions are included in Section 
362.5% 
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3.2.2 Variable Classifications 


There are three types of variables that may be used in function defini- 
tions: 


e dummy variables 
@ local variables 
@ global variables 


Characteristics of these classes of variables are described in the sub- 
sections that follow, along with an explanation of dynamic localization. 


3.2.2.1 Dummy Variables - Variables specified in the header component 
of a defined function (e.g., Z, ARG, LARG, RARG in the examples above) 
are considered dummy vartables. These dummy variables are included in 
the header to define the syntax of the function call. In the function 
body, they hold places for the actual arguments supplied at the time 
the function is called. 


The scope of dummy variables is local to the execution of the function, 
and the values of all dummy variables except the result (Z in the ex- 
amples above) are provided on calling the function. 


3.2.2.2 Local Variables - Variables that have significance only during 
the execution of a particular function are called local vartables. If 
variable A is used in functions F and G, execution of function F does 
not affect the value of A within function G. Variables may be designa- 
ted as local by specifying each variable, preceded by a semicolon, in 
the function header. The following function header: 


VRESEe As 5 TEMF 
establishes I and TEMP as local variables. 


During execution of a function, the local value of a variable is al- 
ways dominant. Local variables are not automatically initialized when 
a function is called, and any local values are lost upon exit from the 
function. 


Function line labels (Section 3.4.2) are treated as local variables 
and are also initialized when the function is called; however, labels 
may not be assigned a value. 


3.2.2.3 Global Variables - Variables that have essentially the same 
significance inside and outside a function definition are considered 
global variables. If a variable is not explicitly defined as a dummy 
or local variable, it is treated as a global variable. A global vari- 
able has the same significance regardless of where it is used, except 
in certain cases of dynamic localization (Section 3.2.2.4) and sus- 
pended execution (Section 3.4.3). 


3.2.2.4 Dynamic Localization - The following description provides an 
example of dynamic localization, which is actually a dynamic form of 
block structuring. If there exist global variables A and 8, anda 
function F is called with local variables B and C, then the global 
value of B is not accessible during the execution of F. If function 

F calls another function named G, with local variable c, then within G 
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any value assigned to C within F is not accessible. Upon return to 
function F, local variable C resumes its former significance. Finally, 
upon exit from F, variables A and B resume their global significance 
and C becomes undefined. 


The name of a function used in function-definition mode refers to the 
most global value of the name. 


3.2.3 Function Input and Output 


The input and output of data values and results of function execution 
are handled by means of the standard APL input/output operators. All 
of the quad symbols implemented in APZ can be used in both immediate 

and function-definition mode. File input and output are discussed in 
Chapter 6. The other varieties of input and output are described in 

detail in Section 2.5. 


One aspect of APL I/O is particularly relevant to a discussion of func- 
tion execution. An input request may be included within an infinite 
loop in a function. In this case, the user may escape from input mode 
by typing the following: 


O<backspace>U 


in APL mode or the mnemonic .OU in ASCII mode. This has the same ef- 
fect as function suspension (Section 3.4.3); it causes function execu- 
tion to be interrupted but does not result in an exit from the function. 


3.2.4 Comment Lines 


Current lines may be included anywhere in an APL program; they are 
particularly appropriate when included in function definitions to 

annotate the statements included in the definition. Comments may 

appear on separate lines or be included on the right end of lines 

containing APL statements. 


The first character in a comment line must be a lamp (a) character, 
formed by overstriking the down union (n) and jot (¢) characters. If 
an ASCII terminal is being used, the first character in a comment line 
must be a double quote ("). The text that follows the comment char- 
acter is treated as a comment and may consist of any combination of 
valid APL characters. A comment ends at the end of the line and cannot 
extend across a line boundary. Examples of comment lines are shown in 
the function included in Section 3.3. 


3.2.5 Examples of Defined Functions 


This section contains examples of the three categories of defined 
functions. 


3.2.5.1 Niladic Function - The following niladic function returns no 
explicit result. 


vy AVG 
C13 TERMITE THE VECTOR TO GE AVERAGED: ! 
C22 VEGTONE TF 
C34 THE RESULT IS '3(+4/VECTOR) +p, VECTOR 
c4i 9 

AVG 
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ENTER THE VECTOR TO BE AVERAGED? 
Oo; 

$35 4467 
THE RESULT IS § 


VECTOR: 
33467 


3.2.5.2 Monadic Function - The following monadic function returns an 

explicit result in AWS. Note that the name of the function, AVERAGE, 

can be used in an arithmetic expression just as an APL primitive func- 
tion could be. 


Y ANSeAVEROAGE VEC 

CL] Ate (+ /VEC yep y VEC 

2] ¥ 
AVERAGE 3 3% 4 6 7 
LOOXAVERAGE 3 5 a & F 


Le 


3.2.5.3 Dyadic Function - The dyadic function included below returns 
an explicit result. AVER is the function name, and NUM and VEC are 
global variables used as function arguments. 


Y RMS ehMLIM AVE VED 





CL] (COMPUTA TTOMAL GUMBER 1 oy ge ilun 
C2] ABE (+/VEC) ep y VER 
ca] 

Li? @vVER 2 3 2 8 % 
COMPUTATIONAL NUMEER 44% 
4 

Li3 Aver & B89 GF 4 
COMPUTATIONAL HUMBER 141% 
? 


114 AVER 7 7 3 0 | 
COMPUTATIONAL NUMBER 1414 
3.6 


3.3 EDITING THE FUNCTION 


A function definition may be altered by the user in a variety of ways. 
Definition lines can be added, deleted, and changed, and the function 
header can be altered. The user must be in function-definition mode 
in order to perform any of the editing functions described in this 
section. 


The function to be edited is "opened" by typing: 
Vfunetton name 


The user may not attempt to enter or change the entire function header 
at this time; there is a special method for changing the header, de- 
scribed in Section 3.3.6. After an addition, replacement, insertion, 
deletion, or display operation, APL displays a line number to allow the 
user to add or enter additional text. If the user does not wish to 
enter text, he can type a del character (V) to close the function and 
thus shift from function-definition to immediate mode. The user may 
also type the V character on an edit line - for example: 


3=5 
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ySTAT 
C77 (C51 MRAM. SUMKSNSUBUSY 


APL replaces line [5] and then exits immediately from function-defini- 
tion mode. 


If the user intends to edit only a single function line, it may be con- 
venient to open the function, specify the line change, and close the 
function, all in a single statement. The replace operation illustrated 
above could be specified in the following way: 


VSTAT [5] MEANKS. SUMHSRSUBUSY 


The V character can be included on any line except a comment line. 


3.3.1 Adding Function Lines 


Lines can be added to the end of a function-definition in a very con- 
venient manner. When an existing function is opened, and an editing 
command is not included on the same line as the del character, APL as- 
sumes that new lines are to be added and displays the next available 
line number. For example, the function name STAT may exist in the fol- 
lowing form before it is edited to remove errors. 


9 STANDXENSUBRS STAT 
Ci SUM & 
l23 SUMK QE ES OX KD) 


rz] RCOMFUTE MEAN, VARTOHCE, STANKARE DEVIATION 
£47] MEANKE SUMMA MSUEBUS 
cS MEANKE SUMM.NSUBS 

9 


The user adds two lines in response to the bracketed line numbers dis-~- 
played by APL. 


VSTAT 
C61 aFUMCTION RETURHS VALUE OF STANDARD DEVIATION OF 
C77 STAMDKEVARKAO,S 
Csi 9 


The user terminates the specification of additional lines by entering a 
VY character to transfer from function-definition to immediate mode. 


3.3.2 Replacing Function Lines 


Existing lines in a function-definition can be replaced by specifying 
the affected line number, followed by the new text of the line. Line 
number [8], displayed by APL below, is simply overridden by specifying 
line [1]. 
VSTAT 
C81 Cid gUMMe+/% 
C2] 9 


The new specification replaces the erroneous contents of line [i]. APL 
then displays the next line number after the replaced line - in this 
case, [2]. The user can enter new text for line [2], can specify 
another line number, or can escape from function-definition mode by 
typing V. This same action could have been performed in a single 
editing line, as shown below. 


VSTATC1] SUMXEE sx 9 
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replacement operation must 
itive number less than 1000. 
than three decimal 


ded in a function body 
line and must be a pos 
1 point but may have no more 


The line number inclu 
refer to an existing 
It may have a decima 
places. 


3.3.3 Inserting Function Lines 


nes between existing lines of the function 
definition by specifying a new line number, followed by the text of 
the new line. To insert a line between [5] and C6], for example, the 
user might specify line number [5.5]. To insert a line before the 
start of the existing function body, any line number in the range [0] 
(function header line) to [1] is valid, as shown below. 


The user can insert new li 


VSTAT 
C8] (CO.5] aSUM ELEMENTS OF ARRAY x 
[0.6] C5.5] VARMe (SUMHOLNSUE) MEAN % 2 
[S.61 9 


The new specifications are inserted between existing lines [0] and [1] 
and [5] and [6] respectively. In each case, APL displays the next 

line number after the inserted line. To derive the line that is "next" 
in an inserted sequence, APL adds 1 to the rightmost digit of the user- 
specified line number. The next line after [0.5] is thus [0.6], the 
next line after [5.5] is [5.6], and the next line after [8.29] is 
[8.3]. The user may enter new text for the line number displayed, may 
escape from function-definition mode by typing V, or may override the 
line number displayed by specifying another line. 


After the function definition is closed, the function lines are re- 
numbered by APL. As in the case of replacement lines, the numbers of 
lines to be inserted must be positive numbers less than 1000, with or 
without a decimal point, and with no more than three decimal places. 
The renumbered function definition now exists in the form shown below. 


VY STAHMOKEHMSURI STAT M 


17 AaSUM ELEMENTS OF arRAYT x 

C27 SUMH E+ / 

C37 BUMN OES CED) ; 

C4] ACOMPUTE MEAM, VARTANCE, STANDARN DEVIATION 
C5] MEQUXE SUMNEHSUBUS 

C6] ME ANKE SUMKENSUES 

C77 VARKE (SUMHDLMSUES ) ME AMM 9 

cel AFUNCTION RETURNS VALUE OF STAMNDORD DEVIATION OF x 
C94 STANDIXEVARN RO, 

v 


3.3.4 Deleting Function Lines 


Existing lines in a function definition may be deleted b ifyi 

y specifying an 
erase character (A), followed by the line number of the line to be Pe 
leted. In the following example, line [5], an incorrect duplicate of 
line [6], is deleted from the function definition. 


APL displays the number of the line just deleted to give the user an 
opportunity to specify a new version of the deleted line. The user can 
enter new text, can specify another line number, or can escape from 
function-definition mode by typing 7. After the function is closed, 
the function-definition lines are renumbered by APL. 


NOTE 


Do not use CONTROL/C to delete a function line. 
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3.3.5 Displaying Function Lines 


The user may display individual lines of the function definition, the 
function definition from a specified line to the end, or the entire 
function definition. To display an individual line, the user specifies 
in brackets the line number of the line to be displayed, followed by a 
quad character ({]). In the example included below, line [3] is displayed. 


VSTAT 
c9a £3or 
C3 BUMK DG / OXKD) 
t31 4 


APL displays the number of the line just displayed to give the user an 
opportunity to specify a new version of the existing line or to over- 
ride the line number with a new line specification. The user can enter 
new text, can specify another line number, or can escape from function- 
definition mode by typing V. 


To display the function definition from a particular line to the end, 
the user reverses the sequence described above by specifying the brack- 
ets the quad character, followed by the line number from which lines 
are to be displayed. The following is an example of such a technique. 


ysTar 
C93 C73 | 
C71 ,_FUNCTION RETURNS VALUE OF STANDARD DEVIATION OF x 
C84 STANOXEVARH RO, 


coy oY 


APL displays the number of the next line after the final line of the 
function definition - in this case [9] - to give the user the oppor- 
tunity to add more text or to specify a different line number. 


To display the entire function definition, the user simply types a 
bracketed quad character with no line specification, as shown below. 


ysTat 
C90 Coo 
Y STANEMEHSUERS STAT 
ci AaSUM ELEMENTS OF AfRAaT 
C21 SUMME4/% 
C32 9 SUMK2E4+/ (0% a2) 
C4] ACOMFUTE MEAH, VARIANCE, STANDARD DEVIATION 
C51 ME ANKE SUMNSHSUB I 
Cé1 VARME (SUMKI-NSURS ) MEAN 42 
C77 AFUNCTION RETURNS VALUE OF STANRARK DEVIATION OF K 
£8] STAMEKEVARK KO, 
9 
col 64 


The V characters preceding line [1] and following line [8] are displayed 
by APL. They indicate the delimiters of the function and identify its 
name. They are not true user-specified del characters and therefore 

do not change the mode. APL displays the number of the next line after 
the final line of the function definition to give the user the opportu- 
nity to add new text or to specify a different line number. 


NOTE 
Any display of a user-defined function 


can be terminated by entering a CTRL/O 
character. 
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3.3.6 Editing the Function Header 


The name or arguments stored in the function header can be edited by 
accessing line number [0] of the function definition. The header line 
can be replaced, displayed, or even deleted temporarily. The following 
example illustrates the display of the function header. 


vSTAT 
C9) CON 
COVSTAHEXENSUERY STAT x 
LO] v 


The user must include a valid specification for the header before 
leaving function-definition mode. 


3.3.7 Renumbering Function Lines 


In function-definition mode, the user is free to include fractional 
line numbers and line numbers that are not immediately consecutive 
(e.g., line [15] followed by line [60]). He may also delete existing 
lines. When the user leaves function-definition mode by entering a 

del character, APZ automatically renumbers the lines of the function 

as consecutive integers, starting at line number [1]. The user should 
ordinarily display the current version of the function at this time, to 
avoid referencing the wrong line numbers the next time he edits the 
function. 


3.3.8 Line-Editing Procedures 


APL allows the user to edit a function definition in the revision mode 
described in Sections 3.3.1 through 3.3.7 or in the line-editing mode 
discussed below. In line-editing mode, the user can alter individual 
characters in an existing line. To modify an APL statement in this 
mode, the user specifies the line number, followed by a quad character, 
followed by the estimated character position at which editing is to 
begin: 


VOTE SEL 
b77 fini94 
Cid AGk % GAMMA —~ 4 + CIMAXX9) 


+ 


APL displays the statement and then on the next line indents to the 
number position specified in the command. The position at which 
editing is to begin is represented by the up-arrow (+t) character in 

the example above; it is the 19th position in the line, counting from 
the first character in the line (e.g., the [ character). The user 

then begins entering edit control characters according to the following 
rules. 


1. Type a slash (/) beneath each character to be deleted. 


2. Type a digit or letter beneath each character before 
which blanks are to be inserted; the particular digit 
or letter represents the number of blanks to be inserted. 
For example, a '2' will insert two blanks to the left 
of the corresponding character in the function line. 
The alphabetic characters are used to insert multiples 
of five blanks. For example, 'A' will insert five 
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blanks, 'B' will insert 10 blanks, and so on. If the 
number of spaces specified plus the current length of 
the line exceeds the current length of the terminal 
line, a DEFN ERROR is displayed. 


3. All other characters typed on the edit control line 
are ignored by APL. 


4. The normal rules of correction-before-entry apply. 
Thus backspacing to insert characters is permitted, 
and creating illegal overstrikes to facilitate retyp~ 
ing of the line is allowed. 


When the carriage returns after the user has finished with the edit 
control line, the function line is displayed without the deleted char- 
acters and with the inserted spaces. The carriage is positioned at 
the first inserted blank or, if no blanks were inserted, at the end 

of the line. The user can then enter new text in the blanked area or 
can make further modifications to the existing text. In this case as 
well, backspacing to insert new characters and creating illegal over- 
strikes to facilitate retyping of the line are allowed. 


Line editing is a multiple-step process. The first step involves de- 
leting characters no longer needed and inserting sufficient blanks in 
the line to allow additional desired text to be typed. The second step 
involves typing in the new text. Repetition of these steps is often 
necessary. The final appearance of the function line should be iden- 
tical to a function line just entered from the keyboard. 


If the user alters the statement number while editing the line, the 
function line corresponding to the new number is altered and the origi- 
nal line remains unchanged. This facilitates the movement to or repli- 
cation of statements in other parts of the program. 


Special processing is also performed if the user specifies a character 
position of zero to the right of the quad character, as shown in the 
following example: 


VSECANT 
EL2J [200] 
C2] SECSPEC*ISEC-I, 


The function line requested by the user is displayed, and the carriage 
stops at the next available character position at the end of the line, 

as shown by the up-arrow (t+) in the example above. The effect is as if 
the line had been entered by the user from the keyboard. The user can 
now add text to the line or can backspace to make corrections. The 
carriage also stops at the end of the line if the number to the right 

of the quad character is larger than the number of characters in the line. 


The following example illustrates the use of line-editing in correcting 
the line: 


[1] T+ (LETTR=STRING/18P,STRING 
There are several errors in this line: 
Ll. LETTER is misspelled cOfLITR, 
2. The right parenthesis has been omitted after STRING. 
3. "8" should not appear after the 1 character. 
4. "P" should be a p character. 
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Because the first error occurs in LETTR, the following command can be 
supplied: 


VFUNC 
C5] [1014] 
C1] T<(LETTR=STRING/1\8P,STRING 


The user now enters the necessary control characters, and APL displays 
the corrected line. 


C1] T+ (LETTR=STRING/18P, STRING 
1 t. f#4. 
ra 7 T+LETT R=STRING /1 ,STRING 


The carriage is positioned at the space between 7 and R, and the user 
simply enters the new characters, spacing over the text to be preserved. 
He types: 


1. "HE" in the space between LETT and R. 
2. ")" in the space between STRING and /. 
3. "“"p" in the space between 1 and ,. 
The new function line is therefore: 
[1] T+«(LETTER=STRING)/19, STRING 


This line is entered as a replacement to the existing function line 
[1] when the user presses the carriage return. 


If the user alters the statement number while editing the line, the 
function line corresponding to the new number is altered and the origi- 
nal line remains unchanged. This facilitates the movement to or dupli- 
cation of statements in other parts of the program. 


3.4 EXECUTING THE FUNCTION 


In function-definition mode, the APL statements that make up a function 
definition are neither executed nor checked for syntactic validity when 
entered. The user simply enters statements, edits them to correct ob- 
vious mistypings and inconsistencies, and saves them for future use. 
The process of defining a function associates the function header pro- 
vided by the user with the statements entered as the function body. 
When the user decides to execute the defined function, he uses the 
function name as he would a primitive APL function. The information 
provided in the function header specifies the number of arguments to 

be supplied in the function call and determines whether or not a value 
will be returned. Section 3.2.5 provides examples of defined functions 
and their corresponding function calls. It is, of course, also possible 
to issue function calls from within other functions. In the implemen- 
tation of APL described in this manual, function calls may be nested 

to a depth of about 30 functions. 


This section provides information on function execution. It focuses 


on branching, suspending, tracing, and locking functions, and using 
the state indicator, 
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3.4.1 Branching Within a Function 


APL statements included in a function definition are normally executed 
in the order determined by their line numbers. Execution begins at the 
first statement following the function header, terminates after the 
last statement in the definition, and is performed only once. It is 
possible to modify this standard order of execution by including 
branching statements in the function definition. The use of branching 
also facilitates the specification of execution loops within the body 
of the function definition. 


The simplest form of an APL branch statement consists of a branch sym- 
bol (+), followed by the number of the function line to which control 
is transferred. For example: 


gy FOO 
CS4 31 


causes an unconditional branch from line [5] to line [1]. Line [1] 
is thus the next statement executed. 


The object of the branch symbol can be a constant, a variable, or an 
expression; it must evaluate to an integer line number within the cur- 
rent function definition to allow execution to continue. If the in- 
teger does not reference a line number in the current function, the 
branch statement causes a return from the function. Users often de- 
liberately specify an out-of~-range-number in order to stop execution. 
A common specification is: 


30 


because 0 references the function header and cannot legitimately be ac- 
cessed by a branch. If the object of the branch is a non-empty vector, 
control passes to the line referenced by the first element of the vec- 
tor. If the vector is empty, the branch statement is not meaningful 
and the normal order of execution within the function definition con- 
tinues. 


Several kinds of condittonal branches can be specified in function 
definitions. In APL, a conditional branch is executed as the result of 
evaluating a logical expression, not in response to any specific IF 
logic. An example of one form of an APL conditional statement is 

shown below. The value of the expression evaluated in the branch 
statement determines either that control will pass to a specified line 
number or that the function will return. 


39x) IMAX 


The logical expression to the right of the +9 specification is evalu- 
ated. If I is greater than IMAX, the value of the expression will be 
9x1 and control will pass to line number [3]. If I is not greater than 
IMAX, then the value of the expression will be 9x0; because line [0] is 
not a legal specification, function execution will return. 


In the second version of the conditional branch, the value of an evalu- 
ated expression determines whether execution will branch to a specified 
line number or continue at the next statement. For example, in: = 


a (VALNCVALS)/INIT 


3-12 


DEFINING AND EXECUTING APL PROGRAMS 


control will pass to the line labeled INIT if the value of the paren- 
thesized expression is true. If it is false, execution will continue 
at the next line after the branch statement. 


3.4.2 The Use of Statement Labels 


Because APL automatically renumbers function lines as consecutive in- 
tegers when the user exits from function-definition mode, branch state- 
ments should generally not refer explicitly to function line numbers. 
Instead, the user can associate a label with a particular statement in 
a function definition and then branch to this statement using the label, 
not the explicit line number, as the object of the branch - for example: 


CAS] TNCR: TeTed 
+ 
+ 


+ 


C274 steer x tc IMAXx 


As shown in this example, a statement label consists of an identifier, 
followed by a colon (:). The internal value of the label is the number 
of the function line with which it is associated - in this case, line 
number [15]. Here a branch to the line associated with the INCR label 
is performed, if I is less than IMAX. 


Labels defined within a function must be distinct identifiers. The 
scope of a label is local to the function in which it occurs, and 
label values are internally respecified upon each exit from function- 
definition mode. The user cannot explicitly define a value for a 
statement label, and a label cannot appear in the function header. 


The following are two examples of defined functions that use branching 
and statement-labeling techniques. Note that function lines containing 
labels are automatically exdented (i.e., begun one character position 
to the left of the rest of the APL text) when the function-definition 
is displayed. 


VReFACTOR TAL i 


C1] Fed 
C23 20x11 Ost (Branch to line [0] (halt) if 0 is 
C3] Rerxi equal to WV) 
CA] ened 
CSI 32 (Unconditional branch to line [2]) 
ié] 4 

YEEeFAC tH 
Cl] xRREROX ytd (Branch to the line labeled NZERO 
C2] ZenxFac Hm if W is equal to 0) 


[C3] aHOTICE THAT RECURSIVE DEFINITIONS 
C4] RARE FERMITTED, 


CSI 70 (Unconditional branch to line [0] 
C6] MEERO? fe] (halt) ) 
[737 9% 
Fac 5 
120 
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3.4.3 Suspending Function Execution 


Function execution is suspended before normal completion if an error 
occurs, if the user types a CTRL/C character, or if a stop vector (see 
Section 3.4.6) is set. When execution is suspended, the name of the 
suspended function and the line number of the statement that would 
have been executed next are displayed. APL then begins a new line, 
indents six spaces, and awaits input in immediate mode. The user can 
perform virtually any APL operation at this time, except for editing 
or erasing the suspended function. 


The suspended function remains active until terminated or until the 
current state indicator or active workspace is cleared. The user can 
resume execution at any time by typing: 


+Line 


where Zine identifies the statement number at which execution is to be 
continued. A suspended function can be terminated by typing: 


70 


The local variables associated with the suspended function remain 
active. The user can examine these variables and can specify their 
values by means of an immediate-mode assignment. 


3.4.4 Examining the State Indicator 


The state indicator, a status vector that resides in the user's active 
workspace, can be examined to determine the status of all active func- 
tions in the APL system. The user can specify an )SI system command 
(Section 5.3.9) to obtain a listing of the active functions, as in the 
following: 


yor 
TEI x 
$£7] 
FI6] 
FES] x 


The listing displays functions in the order in which they were most re- 
cently active. The example included above indicates that execution 

was suspended just before executing statement [1] of function 7, which 
was called during line [7] of function S, which was called during line 
[6] of function R. Before this sequence of calls, execution was sus- 
pended just before executing line [3] of function F. 


In the )SI display, an asterisk (*) following the name and line number 
indicates a suspended funetion, and a blank indicates a pendent fune- 
tion. A pendent function is usually one which is awaiting return from 
another function - possibly a suspended one - which it called. 


The user can also determine from the )SI listing when quad input re- 
quests are pending or an execute operation (¢«) has been invoked. Ex- 
amples of both of these special conditions are shown below. 


73x 
TEL] & 
SE7] 
RE6] 
FESI x 
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€ 

TCAD x 
8E7] 
FES. 
FCS] s 


The user can clear the state indicator by terminating the execution of 
each suspended function in the list, There are several ways to accom- 
plish this. The user may type one right arrow (+) for each function 
marked by an asterisk (each right arrow on a separate line); he may 
issue an 130 I-beam function to clear the state indicator completely 
(Section 4.3.14); or he may clear the state indicator by saving the 
active workspace, then clearing and loading it again (see the )SAVE 
and )LOAD system commands, Sections 5.2.3 and 5.2.4). A cleared state 
indicator is displayed in the form of a blank line. 


The )SIV system command (Section 5.3.10) can be used to obtain a more 
extensive display of the state indicator. In addition to the informa- 
tion accessible to )SI, )SIV returns a list of local variables for 
each function displayed. The following is an example of an )SIV 
display. 
yGIV 

TREIGELY *« a Qk 

TEL] « M 

co eae 

KEOI 

PER] k 





This indicates that the variable W local to function 7 is currently 
dominant, and that the variable N local to function S is currently in- 
accessible. 


3.4.5 The Trace Vector 


The user may find it helpful for debugging purposes to obtain an auto- 
matic display of the intermediate results of function execution. As a 
program tracing aid, the values computed by one or more function state- 
ments can be output each time those statements are executed. To estab- 
lish a trace for function F, the user specifies a vector in the 
following format: 


TaFe4 & 7 
For each execution of the line numbers [4], [6], and [7], this command 
causes the following information to be displayed, in the order shown: 
function name 
bracketed statement line number 
final value returned by the statement 
If the statement being traced is a branch statement, then the value 
printed is the value to which control is passed by the branch. 
To trace all the statements of a function F, the following specification 
can be supplied if the index origin is currently set to 1: 


TAFE YH 
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where W is a number at least as large as the number of statements in 
F of the index origin is 0, the user issues the statements. 


because the function neader (line 0) cannot be traced. To disable the 
trace vector for function fF, the user includes either of the following 
statements: 


TAFtO 
TaFe1d 


A new trace vector does not override an existing specification. If 
lines [4], [6], and [7] are currently being traced, the user may add 
line [5] to this list simply by entering trace vector: 


TAF ES 


However, to omit line [6] from an existing trace vector, the user must 
disable the trace vector for the function and then enter a new trace 
vector, as shown in the following: 


TAFGe1O 
TaFe4 3 7 


NOTE 


Editing a line for which a trace vector 
has been defined causes the trace to be 
disabled for that line. 


The following is an example of a function definition followed by two 
executions of that function, the first with the trace vector enabled. 


9 AHSWHEPACTORTAL H ZF CGUNT 
cil ACALCLATES FACTORIAL OF i 
C2] AHSWRe 1 
C3] (02H) /D 
Cay ANSWKEHXxFACTOR IAL M-7 

? 


TAFACTORTALGE2 3 4 

FACTORIAL 4 
FACTORIALL 2] 4 
FACTORIALL 3] 
FACTORIALL2?] 4 
FACTORIALL 3] 
FACTORLALL 2) 4 
FACTORIALLZ] 
FACTORTALL2] 
FACTORIALL 3] 
FACTORIALL 24 
FACTORIALL 3] 
FACTORIALL 4} 
FACTORIAL 4] 
FACTORIALL 4 
FACTORIAL[L 4] 
24 


Ps 


hO he Or 


4 


TAF ACTOR LAL 1O 
FACTORIAL 4 
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3.4.6 The Stop Vector 


APL allows the user to suspend execution of a function from within the 
function itself by specifying a stop control vector. The syntax of 
this vector is similar to that of the trace vector. The stop vector 
can be used to suspend function execution just before execution of one 
or more specified statements. To cause function F to be suspended 
before executing line [12] and line [19], the user includes the 
following statement in the function definition: 


SAFe12 19 


For each suspension, this command displays the function name and line 
number that was about to be executed. To disable the stop vector for 
function F, either of the following specifications may be supplied: 


S4F¢O 
BAF EVO 


After function execution has been suspended by means of the stop con- 
trol vector, the system is in the normal suspended state. An entry is 
included in the state indicator, identifying the suspended function 
and the line at which it was suspended. Execution can be resumed by 
specifying a branch to the desired line number. 


Execution of a function cannot be suspended before line 0 (the function 
header). The stop control vector can be set from within a function to 
cause suspension only under certain circumstances. 


NOTE 


Editing a line for which a stop vector 
has been defined causes the stop vector 
to be disabled for that line. 


An example of the use of the stop vector is included below. 


BAR AC TORE Ah. ge 0% 
Fee ror: Dat. a 


FACTORIAL 3%] 
yO XE 
FACTOR TALL 4] x» 


FACTORIALL 3] 
45 


FACTOR TAL [3 7 


FACTORIALL 37 


FACTORIAL [ 3} 

24 
BAF AC TOME EAL 1 O 
FACTOR Tah. 4 


DEFINING AND EXECUTING APL PROGRAMS 


3.4.7 Locking a Function 


It may be desirable to prohibit users from changing and possibly damag- 
ing existing function definitions. APL allows a user to lock a func- 
tion definition in order to protect it from unauthorized use, to main- 
tain security, or to treat a function as a proprietary program. To 
create a locked function or to lock an existing function, the user 
closes the function-definition with a del-tilde (¥) character rather 
than a simple del (V). The ¥# is created by overstriking VY and ~. The 
following example illustrates the locking of a previously unlocked 
function-definition. 


V TRIG 
[19] e 


A locked function cannot be edited in the manner described in Section 
3.2. Function lines cannot be added, changed, deleted, or displayed 
for locked functions. Trace and stop control vectors cannot be defined 
or changed for the function. Any trace or stop settings in effect at 
the time a function-definition is locked are automatically nullified. 


If an error occurs during execution of a locked function, the function 
name and the line number at which the error occurred are displayed, 
but the contents of the statement are not included in this display. 
APL then causes an exit to immediate-mode. 


CHAPTER 4 


APL SYSTEM VARIABLES AND I-BEAM FUNCTIONS 


4.1 INTRODUCTION 


There are a variety of ways in which the user may communicate with the 
APL system in order to change system parameters, determine hardware or 
operational characteristics, and modify processing methods. The system 
commands documented in Chapter 5 facilitate many of these system 
operations. The system elements described in this chapter allow APL 
users to communicate with the system from within the APL language 
itself. These elements are subject to the APL language syntax and 
rules of function definition. They may be included in AP functions 
and defined in conjunction with other language operations. 


The system elements described in this chapter can be grouped in two 
categories: system variables and I-beams. In some cases, system 
variables and I-beams perform related functions. In other cases, these 
system features provide alternative ways of performing operations 
invoked by the APL system commands. 


4.2 SYSTEM VARIABLES 
System variables have been implemented in this version of APL to 


facilitate communication with the APZ system. They are used to perform 
such operations as the following: 


e set the index origin and relative fuzz 

e change the output precision and line width 

e reference the characters in the collating sequence 

© report on executing functions and available workspace area 


System variables are syntactically similar to ordinary variables and 
may be used in any language expression or function. System variables 
differ from ordinary variables because of their special significance 
to the system. System variable names are distinguished names; they 
begin with a quad (]) character and cannot be used for user-defined 
purposes. They cannot be copied, erased, or collected in a group by 
means of the APZ system commands (see Chapter 5). 


The system variables described in this section are considered shared 
variables because they are shared by the user's workspace and the APL 
processor and serve as an interface between the two. The sharing 
facility is invoked automatically when the workspace is activated. 
Sharing implies that the workspace and processor may each use values 
specified by the other, as appropriate to the particular operation 
being performed. It also implies that the value of a variable being 
used in a workspace may sometimes be different from the value last 
specified by the user of the workspace. The variables described in 
this section fall into two categories: 
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& System variables that assume the value provided by the 
user and retain it until the user overrides the value or 
clears the workspace. These variables are described in 
Sections 4.2.1 through 4.2.5 and have default values in 
effect when the workspace is loaded. An example of such 
a variable is OPP, which is used to determine the precision 
of numeric output. If the value specified by the user is 
invalid for the operation, APL will return a DOMAIN FRROR 
when the assignment is attempted. 


e System variables that retain the values supplied by the 
APL system. Because of their syntactic similarity to 
ordinary variables, these system variables can be set by 
the user; however, they will continue to have the values 
supplied by the system. These variables are described in 
Sections 4.2.6 through 4.2.8. 


4.2.1 UCT: Establishing the Comparison Tolerance 


Default: 5E 15 (double-precision) 
5E 7 (single-precision) 
Example: _OCT 
1E 13 _ 
OCT<+1E 15 





The [C7 system variable is used to set the degree of tolerance or rela- 
tive fuzz to be applied in performing comparisons. It is used in con- 
junction with the relational operators: (<, <, =, 2, >, ¥) and with 
the dyadic-index (1) and membership (<«) functions and floor (L) and 
ceiling (ff). 


The OC? value specified by the user is saved when the active workspace 


is saved. See the description of fuzz in Section 2.4.3. The value 
for OCT must be in the range O<QCTs approximately .38. 


4.2.2 70: Setting the Index Origin 





Default: al 
Example: (J0 
4 
DL0<o 
23 
Qf 2 


The ZO system variable is used to change the setting of the index 
origin. This setting is important in array operations and in conjunc— 
tion with roll and deal (Sections 2.7.19 and 2.7.20) and iota (Sections 
2.7.5 and 2.7.6). The value of O00 is saved when the active workspace 
is saved and is only meaningful if it is 0 or 1. This variable is 
equivalent to the )ORIGIN system command (Section 5.4.1). 


4.2.3 OPP: Determining the Output Precision 


Default; 10 (double-precision) 
6 (single-precision) 


Example: IPP 
10 
DOPP<+15 
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The OPP system variable is used to determine the precision of non- 
integer output by setting the number of significant digits to be 
displayed. It is also relevant to the expression of characters by 
means of the monadic format (¥) function (Section 2.7.32). Legal 
values for OPP are integers in the range 1 through 7 for single- 
precision systems and 1 through 17 for double-precision systems. 
This system variable does not affect the precision of internal 
calculations or the display of numerical constants. The precision 
specified by the user is saved when the active workspace is saved. 
PP is equivalent to the )DIGITS system command (Section 5.4.2). 

















4.2.4 PW: Determining the Width of the Output Line 











Default: 120 


Example: OPW 
120 
OPW<130 








The DPW system variable is used to set the maximum number of characters 
that may appear in an output line. Legal values for OPW are integers 
in the range 30 through 384. It does not affect the display of messages 
on the terminal or the allowable length of input lines. The width 
specified by the user is saved when the active workspace is saved. 

OPW is equivalent to the )WIDTH system command (Section 5.4.3). 


4.2.5 ORL: Setting a Random Link 
Default: 0 
Example: ORL<« 1+2*15 


The ORL system variable is used to set the sequence used by the pseudo 
random number generator in APL. This random number generator is used 
in the APL roll and deal functions (Sections 2.7.19 and 2.7.20). The 
value of ORL is the starting point of the chain used to generate the 
numbers. This system variable has a meaningful range of 0 through 

1+2*15. The value of ORL specified by the user is saved when the 
active workspace is saved. 














4.2.6 AV: Storing a Vector of Characters 





Example: JLINEFD<DAVL[99] 


The DAV (atomic vector) system variable is a vector containing all 
possible characters; DAV is 256 elements in length and is used to 
express the binary representation of any character in the APL system. 
For example, if the index origin setting is 0, the following expression 
refers to the carriage return, backspace, and line feed characters: 


QAVL10 8 13] 
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The indices associated with any of the APZ characters can be retrieved; 
if the index origin is 0, the following expression returns the elements 
shown below. 


OAV1'ABCABC' 
97 98 99 150 1514 152 


Many of the elements of the atomic vector are non-printing characters, 
and some do not even exercise control. 


See the discussion of relational functions in Section 2.6.4. 





4.2.7 O2ZC: Reporting on Executing Functions 


Example: ~OLC 


The (ZC (line counter) system variable is used to obtain a partial 
report on functions that are currently being executed. It is stored 
as a vector of the line numbers contained in the state indicator, 
arranged in order of most recently suspended function first. OLC is 
particularly useful in branch statements; the user can simply specify 
that execution is to resume immediately following the line number at 
which function execution was most recently suspended, as shown in the 
example above. [LC is related to the following I-beams: 


I-beam Meaning 
I27 Vector of line numbers of functions in 


the state indicator 


I26 Current value of the first line number 
in the state indicator 





4.2.8 OWA: Reporting the Available Working Area 


Example: OWA 
20000 


The QWA system variable is used to determine the maximum amount that 
the active workspace may increase. The size is given in bytes and is 
obtained by subtracting the current low-segment size from the maximum 
low-segment size. OWA is equivalent to r-beam 22, which also returns 
the available working area. 


4.3 I-Beams 


There are two types of I-beam functions. The first type consists of 
functions used to return information about the user's workspace and 
the APL system. The following are examples of information returned by 
the tI-beams in this category: 
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@ Symbol table size 

e Date and time of day 

e Terminal character set 

e Line numbers of functions in the state indicator 
e Precision of APL version 


Some of these I-beams report general system characteristics (e.g., 
date) and others return information relevant only to the particular 
user's workspace and session (e.g., line numbers of suspended func- 
tions). 


The second type of rI-beams consists of functions used to perform 
system actions and to change workspace parameters. The following are 
examples of actions performed by the I-beams in this. category: 


e Turning on and off error displays for the execute operator 
® Clearing the state indicator 

e Terminating the APL session 

® Changing the random number sequence 


I-beam functions are initiated by means of the following format: 


rA 


where the I character is formed by overstriking the T and 1 characters. 
The A argument is a number identifying the particular function to be 
invoked. A may be a constant or a variable. It must be a scalar or 

a one-element array. 


4.3.1 115: Reinitiating Error Displays for the Execute Function 


Example: 
xlé 
€ ‘Keng! 
xi 
eg BEDXg! 


VALUE ERROR: 
eeox 9 
4 


I-beam 15 turns on the display of error messages for the execute (ce) 
function after these messages have been suppressed by I-beam 16 
(Section 4.3.2). If an error is encountered while APL is processing 
an execute string, the system does not display an error message or 
echo the line in which the error occurred if I-beam 16 has been 
issued. To reinitiate error displays for the execute function, the 
user may specify an 115 function. The execute function is described 
in detail in Sections 2.7.24 and 5.6. 
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4.3.2 116: Suppressing Error Displays for the Execute Function 
Example: 


¢')COFY FOO! 
?Can’t find file or account 


x16 
Aes ' CORT FOO! 
fr 


PA 


I-beam 16 turns off the display of error messages for the execute (e«) 
function. If m-beam 16 has been issued and an error is encountered 
while APL is processing the execute string, execution is interrupted 
but the system does not display an error message and echo the line in 
which the error occurred. This allows the user to retain control, to 
handle the error condition under program supervision, and to continue 
executing the function if desired. After an error has been detected, 
the value returned by the execute string is a null array whose shape 
is 0 FE, where F£ is a number indicating the error that was encountered. 


In the example at the beginning of this section, error number 
occurred, because the specified file could not be located. Appendix D 
contains a complete description of all APL error conditions. 


To turn on the display of execute error messages after they have been 
suppressed, the user may issue I-beam 15 (Section 4.3.1). 


4.3.3 118: Returning the Condition of the Workspace 


Example: 


218 
16) 


I-beam 18 returns the condition of the active workspace. A value of 0 
indicates that the workspace is intact, and a value of 1 indicates 
that the workspace has suffered some kind of damage. If 1-beam 18 
returns a value of 1, the user should correct the damage by clearing 
the active workspace with a )CLEAR system command (Section 5.2.1) or 
replacing it with a )LOAD (Section 5.2.3) command. 


4.3.4 1220: Returning the Time of Day 
Example: 

x20 

2897083 


24 60 60 60rx20 
13 22 11 40 
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I-beam 20 returns the current time of day as time since midnight in 
60ths of a second (50ths of a second in Europe). The user may apply 
an APL encode (tT) function to the returned value to format the time in 
hours, minutes, seconds, and 60ths of seconds. This is illustrated in 
the second example above. 


4.3.5 221: Returning the CPU Time (RSTS/E Only) 
Example: 


zi 
8844 

24 60 40 607x211 
oO 1 37 24 


I-beam 21 returns the CPU time expended since the user signed on in 
the current APL session. Time is expressed in 60ths of a second 
(50ths of a second in Europe). As illustrated in the second example 
above, the user may apply an encode (T) function to the returned 
value to format the CPU time in hours, minutes, seconds, and 60ths of 
seconds. 


I-~beam 21 is useful in comparing the execution times of different 
programs. It may also be included in a function, and the execution 
of that function made dependent on the compute time used so far in 
the session. 


I-beam 21 is a RSTS/E function; under RT-11, RSX-11M and IAS, it 
returns a "NOT YET IMPLEMENTED" error. 


4.3.6 122: Returning Workspace Availability 
Example: 


4) 


Thal 


16394 


I-beam 22 is used to measure the maximum amount that the active work- 
space may increase. The size is given in bytes. iI-beam 22 may be 
used in a function whose execution is dependent on the amount of free 
space available in the workspace. 


4.3.7 123: Returning the System Job Number (RSTS/E Only) 
Example: 


x23 


Li 


I-beam 23 returns the system job number associated with the user's 
current APL session in base 10 notation. This I-beam is a RSTS/E 
function; under RT-11, RSX-1LIM, and IAS, it returns a value of zero. 
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4.3.8 3125: Returning Today's Date 
Example: 


nt 

BOS79 
SecBr Loo eres 
ro) 

3 5 79 


I-beam 25 returns today's date in base 10 notation in the form MMDDYY. 
As illustrated in the second example above, the user may apply encode 
(T) and rho (p) functions to this returned value to format the date 

as a three-element vector. 


4.3.9 226: Returning a Line Number 


Example: 
FUME] 


FURCQE 2] 
yBE 
FUMCOL 24 x 
FURCIT ILI 
rd 
5 


ae 


I-beam 26 returns the line number of the statement currently being 
executed or about to be executed. The scalar returned by I-beam 26 

is the first line number in the state indicator (Section 3.4.4) and 
the first element of the vector returned by I-beam 27 (Section 4.3.11). 
This number represents the line at which the innermost function was 
suspended. If APL displays a blank line, this indicates that the 
state indicator is empty and no functions are currently suspended. 


I-beam 26 is particularly useful in branch statements. The user can 
simply resume execution of the innermost function by specifying +126, 
as shown in the example, rather than entering the line number displayed 
at the time the last function was suspended. To branch two lines from 
the current line in the suspended function, the user specifies +2+126. 


4.3.10 227: Returning a Vector of Line Numbers 
Example: 


yer 
FUNCOL2] x 
FUNCIEL] 

me? 


2d 


I-beam 27 returns a vector of function line numbers currently in the 
state indicator (Section 3.4.4). The first element of the array is 
the line number that would be returned by I-beam 26 and represents 
the line at which the innermost function was suspended. If APL 
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displays a blank line, this indicates that the state indicator is 
empty and no functions are currently suspended. 


I-beam 27 is an aid in resuming function execution without including 
a specific line number at which the function was suspended. The user 
may define function RES, as shown in the example below, and then 
resume execution of the second function in the state indicator by 
entering >RES. 


yy AGREES 
Cid Ae¢x27 29 
C23 94 

RES 
a“ 
EME QUT TOM & TOF 
FUHC OE |p hee 

4 


4.3.11 128: Returning the Terminal Character Set 
Example: 


128 


I~beam 28 returns a value indicating the character set specified for 
the user's terminal. The value returned by this I-beam is one of the 
following: 


Value Meaning 
0 APL character set 
1 ASCII character set 


The character set is selected at the time the user begins the APL 
session (Section 1.5). 


4.3.12 129: Returning the User's Project-Programmer Number 
(RSTS/E Only) 


Example: 


ree 
129 149 


I-beam 29 returns the project-programmer number of the APL user as a 
two-element vector in base 10 notation. This I-beam is a RSTS/E 
function; under RT-11, RSX-11M, and IAS, it returns two zeroes. 
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4.3.13 130: Clearing the State Indicator 


Example: 


x30 
yer 


I-beam 30 clears the state indicator. It is equivalent to typing a 
series of right arrows (+), one for each suspended function. I-beam 
30 removes all pendent and suspended function calls from the system. 
As shown in the example, an )SI system command (Section 5.3.9) issued 
after the I-beam results in the display of a blank line, or null 
vector. 


If several errors have occurred during function execution, 1I-beam 30 
should be specified before a )SAVE system command (Section 5.2.3) is 
issued for that function. See Section 3.4.4 for a discussion of 
alternative ways of clearing the state indicator. 


4.3.14 136: Terminating the APL Session 
Example: 
rs 


Read: 


I-beam 36 exits from the APL system and returns control to command 
level. This I-beam performs the same function as the )OFF system 
command (Section 5.5.1). Under RT-11, the APL user returns automat- 
ically to system command level after issuing 1-beam 36. RSTS users 
return automatically to the BASIC environment, as illustrated in the 
example above. RSX-11M users return to the Monitor Console Routine 
(MCR). IAS users return to the Program Development System (PDS). 


4.4 SYSTEM FUNCTIONS 


The version of APL described in this manual supports a variety of sys- 
tem functions, implemented as part of the APL shared variable facility. 
The six system functions described in this section allow the user to 
perform such operations as the following: 


e Express the canonical representation of a function 
and store function definitions as data 


® Erase a named object 


e Construct a name list of labels, variables, or func- 
tions and return the classification of a named object 


System functions are an integral part of the APL language and may be 
used freely in all APL function definitions. They can be clearly dis- 
tinguished from the primitive functions available in the APL language; 
like system variables, the names of the system functions described in 
this chapter begin with a quad (0) character and are reserved for the 
use described below. And like system variables, these functions can- 
not be copied, erased, or collected in a group. 
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4.4.1 QCR: Obtaining a Canonical Representation 


Format: OCR A 
Rank: 12ppA 
Example: OCR 'TRIG' 


The 0cR system function is used to obtain a canontcal representation 
of a defined function. OCR operates on a character array that identi- 
fies the name of the function; this array is represented by A in the 
format above. A canonical representation of a defined function is a 
character matrix with rows consisting of the original lines of the 
function definition, reformatted to be of equal length. The V symbols, 
line numbers, and brackets are removed from the definition. Lines that 
contain labels are shifted to the right so all text begins at the same 
character position. Lines are then right-padded with blanks to make 
all lines equal in length to the longest line of the function. This 
reformatting allows the function definition to be treated as data. 

The example shown below illustrates the original function to be refer- 
enced by UCR and the matrix or canonical representation that results 
from the operation of the system function. 








VMEANCOIV 
V MEANX<«NSUBJ MEAN X 
C4] ASUM VECTOR X 
[2] SUMX<+/X 
L3] MEANX*«SUMX+NSUMS 








A<QCR 'MEAN' 
A 
MEANX<NSUBJ MEAN X 
ASUM VECTOR X 
SUMX<+/X 
MEANX<+SUMX+NSUBJ 
pA 
4 18 
x86 39 54 21 7 #8 
10 MEAN X 
4.9 


If the A argument in the UCR function does not represent the name of 

a defined and unlocked function, the resulting matrix is of dimension 
0 by O. APL returns a RANK ERROR if A is not a vector or scalar and 

a DOMAIN ERROR if the argument is not a character array. 





4.4.2 FX: Establishing a Function 








Format: OFX M 

Rank: 2=o00M 

Example: DFX A 
TRIG 





The OFX (fix) system function effectively reverses the operation per— 
formed by DCR. This function operates on a character matrix that 
contains a canonical representation of a function; this array is 
represented by M in the format above. It establishes in the user's 
workspace a function that has the name of the function associated with 
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the canonical representation M. If a function with the same name 
already exists in the active workspace, OFX will replace it. The 
matrix identified by M is not affected by the OFX operation. The 
following example can be considered a continuation of the example 
begun in Section 4.4.1. 


AL3;6]<'x' 

OFX A 
MEAN 

VMEAN([OIV 

VY MEANX<+NSUBJ MEAN X 

bag ASUM VECTOR X 
C2] SUMX+*x/X 
[3] MEANX<SUMX+NSUBJ 





Vv 
Xx 
§ 6 3 @ & & 214A TFT & 
10 MEAN X 
P4H5152 


Another example of the use of OFX in conjunction with the execute 
operator is shown below. 





e('i10 ',OFX A),* x' 
LH Lie 











The normal rules about local names apply to the names of any functions 
established by the OFX function. If the BG function is fixed within 
function Z and the name BG is a local one, the BG definition is not 
preserved after execution of the Z function comes to an end. Standard 
function-definition mode applies only to global names. 


OFX will not establish a function if the name of the function to be 
established is the same as that of an existing label, variable, or 
group or an existing function that is currently pendent or suspended. 
A pendent function is usually one that is awaiting return from another 
function. [FX will execute properly if the matrix referenced by [FX 
is identical to a canonical representation except for the addition of 
blank characters in rows other than those consisting only of blanks. 
If OFX cannot establish a function, a scalar index representing the 
row in M where an error was found is returned. No change is made to 
any function or matrix in the user's workspace. APL returns a RANK 
ERROR if M is not a matrix and a DOMAIN ERROR if the argument is not 
a character array. 


4.4.3 OFX: Erasing a Named Object 


Format: DEX A 
Rank: 22ppA 
Example: DEX 'ABMAX' 


el 


The OFX (expunge) system function is used to erase an existing use of 
aname. (Q#£X operates dynamically on a character array that identifies 
the name to be erased; this array is represented by 4 in the format 
above. This function has capabilities similar to those of the )FRASE 
system command, except that it cannot erase a named object that refers 
to a label, a group, a suspended or pendent function, or a system 
variable. In addition, MEX operates only on global or dominant local 
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variables. It is used particularly to avoid conflicts that may occur 
because of duplicate occurrences of the same name in the APL workspace. 
Q#2X¥ applies to a matrix of names and produces as a result a logical 
vector. It returns a value of 1 if an existing version of a name is 
successfully erased and the name is now free to be used, as shown in 
the example above. If the name cannot be erased for any of the reasons 
described, a result of 0 is returned. A 0 result is also returned if 
the A argument does not represent a legal APL variable name. APL 
returns a RANK ERROR if A has a rank higher than that of a matrix and 

a DOMAIN ERROR if the A argument is not a character array. 


4.4.4 QNL: Constructing a List of Labels, Variables, or Functions 


Monadic Form: 


Format: OWL WN 
Rank: 12>90N 
Example: LIST<QWWL 2 


Dyadic Form: 


Format: A QNE N 
Rank: 12ppN 

12ppA 
Example: 'GKM' OWL 1 3 


The ONL system function is implemented in both monadic and dyadic 
form. Both forms of the function are used to construct a list of 
named objects residing in the active workspace. The W parameter is 
included in both forms of the function to identify the type of named 
objects to be included in the name list. The parameter is an integer 
scalar or vector that can have one of the following values: 


Values Meaning 
1 Labels 
2 Variables 
3 Functions 


For example: 

X<«QNEL 1 2 
causes the names of all labels and variables in the workspace to be 
included in name list X in alphabetical order. Each row of the matrix 
will contain the name of one label or variable. 
The dyadic form of the [WZ function allows the user to restrict the 
name list to names beginning with specified characters by including 
an A parameter in the command. For example: 


NLIST<'ABCDEF' QWL 3 
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causes a name list to be constructed of function names whose initial 
letters are A through F; the list is arranged in alphabetical order. 
The A parameter must be a scalar or vector of alphabetic characters. 
The letters supplied in the character string must be included in 
alphabetic order. 


The OWL system function can be used for a variety of purposes. Some 
of these are described below. 


e OWL can interact with DCR in creating functions that 
can automatically display the definitions of all ora 
subset of functions in the workspace. It can also be 
used to analyze interactions between variables and 
functions. 





e In its dyadic form, ONL can guide the user in choosing 
names while developing or interacting with a workspace. 


e In conjunction with OFX, the OWL function can cause 
all of the named objects in a certain category to be 
erased dynamically. It also facilitates the design 
of a function that can be used to clear a workspace 
of all but a preselected collection of named objects. 


The following example illustrates the construction of a matrix contain- 
ing the names of variables in the active workspace that begin with the 


letter V/V. 


NLIST<«'V' QNL 2 
NLIST 

VAR1 

VAR2 

VAR203 

VAR204 

VARS9 

VBMAX 


4.4.5 NC: Returning a Name Classification 

















Format: Onc A 
Rank: 22004 
Example: NC 'VARSQ'* 


2 


The ONC system function is used to return the classification of a 
name or series of names. [NC operates on the matrix, vector, or 
scalar represented by argument A. If A is a character matrix, UNC 
returns the class of the name represented by each row of A. If A 
is a vector or scalar, OWC returns the classification of a single 
name. The ONC function returns a numerical value representing each 
name classification as follows: 
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Value Meaning 
0) Name available for any use 
4 Label name 
2 Variable name 
3 Function name 
4 Not available for use as a name 


A value of 4 implies that argument A is not a valid name or that it 
is currently in use as a group name. 
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CHAPTER 5 


SYSTEM COMMANDS 


5.1 OVERVIEW OF SYSTEM COMMANDS 


A wide variety of system commands have been implemented to provide 
a means of communicating with the APL system and controlling the 
operational environment in which an APL session is conducted. 
System commands allow the user to examine or change the state of 
the system in such ways as the following: 


® Clear, name, and save the active workspace. 

e Load and delete a workspace from a secondary storage 
device. 

® List variable and function names. 

e Display the status of functions and local variables in 


the workspace. 


e Set and display the index origin, maximum number of 
significant digits, output line width, and comparison 
tolerance. 


System commands are not considered a part of the APL language itself, 
but can be viewed as an interface between the user and the language 
processor. System commands implemented for use with the APZ file 
system are described in Chapter 6. Appendix B provides a summary 

of the format of all system commands, in alphabetical order. 


This chapter is structured in the following way. Section 5.1 
provides an overview of the format, function, and interaction of 
system commands. Sections 5.2 through 5.5 describe the system 
commands implemented for use with APL in the following categories: 


Section Commands 
542 Basic workspace-control commands 
5.3 Workspace-content commands 
5.4 Workspace-environment commands 
5.5 APL termination commands 


Section 5.6 discusses the special function of the execute operator (e) 
in relation to system commands. 
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5.1.1 System Command Format 


System commands begin with a right parenthesis, as shown in the 
following format: 


Jecommand-name {parameter-list] 


Some system commands require the inclusion of one or more parameters 
or arguments in the command line. If required or optional parameters 
are included, at least one space must separate the individual elements 
of the system command. 


The examples included below illustrate the format of several system 
commands. 


CLAP: (No parameters required) 
UTGITS 6 (Parameter required) 
)VARS @ 


(Parameter optional) 


JERASE @& FC © (One or more parameters required) 


5.1.2 Action and Inquiry Commands 


APL system commands may be used in two distinct modes: action and 
inquiry. Action commands invoke some change in the state of the 

APL system. Inquiry commands report on the state of the system but 
do not change this state in any way. The /ORIGIN command is an example 
of an action command. It indicates the index origin to be used 
during the current APL session and is specified in the following 

way: 


LOR LGM 2 
WAG | 


The )SZI command, on the other hand, operates in inquiry mode and is 
used to report on the status of APL program execution. It is issued 
as shown below: 


)er 
FUHCOLLT * 
FUHOY OL 


The )WSID command may be used in both action and inquiry mode. In ac- 
tion mode, )WSID assigns the name included in the command line as the 
new name of the active workspace and returns the previous name of the 
workspace. In inquiry mode, )WSID is issued without an argument and 
returns the current name of the active workspace. The following ex- 
amples illustrate the two forms of the )WSID command. 


ywsrn 
BOZO 


5.1.3 APL Workspaces 


The APL system uses a buffer in the user's memory area to store func- 
tions, variables, values, information on the status of functions, and 
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any temporary results obtained while executing APL statements. When 
available in memory, this buffer area is known as the active workspace. 


The user may issue system commands that cause this active workspace 
to be saved on a secondary storage device; the saved workspace can 
subsequently be loaded into the buffer area to function as the active 
workspace once again. The term "workspace" is used to refer either 
to the active workspace or to a version of an active workspace now 
saved on secondary storage. 


Many of the system commands described in this chapter have been 
implemented to facilitate workspace-manipulation operations. The 
APL user has extensive control over the activity and characteristics 
of the workspace in his system. The workspace can be cleared, named, 
saved, loaded, and deleted. The names of functions and variables in 
the active workspace can be displayed. The user can change such 
active workspace characteristics as index origin setting, number of 
significant digits in output, and comparison tolerance. 


Each APL workspace defined in a user's disk area has a unique name 
associated with it. This workspace name is represented by the 
filename parameter in many of the system command formats included 
in this chapter and in Chapter 6. 


In RT-1ll systems, filename has the following format: 
devtce:name.extl size] 


All of these fields are optional. The name component must usually 

be supplied, but can be omitted if an output device name is specified, 
as in the filename LP:. If a file sise is specified, it must be 
enclosed in square brackets. 


In RSTS/E systems, several additional components may be included in 
the filename format, as shown in the following example: 


device:name.ext<prot>[prj,prg]/SIZE:stze/CLUSTER:clus/MODE:mode 
As in the RT-11 format, all fields are optional. 
In RSX-11M and IAS systems, filename has the following format: 
devtece:Lutelname.ext;version 


In all systems, a comma should be inserted instead of a period to 
separate the name and ext components when an ASCII terminal is being 
used (see Section 1.3.2). 


Table 5-1 summarizes the characteristics of each filename component. 
Alphanumeric characters included in device, name, and ext fields 
may be letters (A-Z) and numbers (0-9). 


Detailed information on these filename components is included in the 
BASIC-PLUS LANGUAGE MANUAL. 


Examples of legal filenames are included below. 


RTFILE.TXTC SI 
RSTSFL.TXT/SIZE?3 
RSXFIL.TXT#2 
(RT-1l1 only) 
(RSTS/E only) 
(RSX-11M and IAS only) 
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Table 5-1 
Filename Components 


All systems: 


device Valid device name with optional unit number, 
followed by a colon - for example: 


TGP e 
DTS* 


The default device name is SY:. 


Filename consisting of a maximum of six alpha- 
numeric characters (nine for RSX-11M), begin- 
ning with a leter - for example: 


TEMP 
FILOO1 


There is no default. 


Period or comma, followed by a maximum of three 
alphanumeric characters - for example: 


« PMP 
»APL 


For most system commands, the default exten- 
sion is .APL. For the )SAVE and )LOAD 
commands, the default is .APC. 


RT~11 only Size of the file in blocks of 512 bytes each. 

size The size is used in reserving room for output 
files and by the )CREATE command (Section 
6.3.2) to allocate space for new files. It 
must be enclosed in square brackets - for 
example: 


[2048] 


RSTS/E only: 


prot Protection code used in creating a new file. 
A code of <40> allows other users to read but 
not to alter a file. It must be enclosed in 
angle brackets - example: 


<UQ> 
Default is the system default. 
Project-programmer number (in decimal) of the 
disk area in which the file is stored. It 
must be enclosed in square brackets - for 
example: 


[7,34] 


Default is the user's project-programmer 
number. 
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Table 5-1 (Cont.) 
Filename Components 


Slash, followed by the size of the file in 
blocks of 512 bytes each. It must be speci- 
fied as a /SIZE switch ~ for example: 


/SIZE:16 
There is no default. 
Slash, followed by the cluster size associated 


with the file. It must be specified as a 
/CLUSTER switch - for example: 


/CLUSTER: 64 
There is no default. 


Slash, followed by the mode associated with 
the file. It must be specified as a /MODE 
switch - for example: 


/MODE: 1 
There is no default. 


RSX-11M and IAS 
only: 


ute Project-programmer number (in octal) of the 
disk area in which the file is stored. It 
must be enclosed in square brackets - for 
example: 


[100,11] 
Default is the current user default. 


verston A single octal number in the range 1-77777 
representing the desired version of the file. 
(Note that RSX-11M and IAS allow multiple 
versions of a single file to be stored.) 
Default is the highest available number. 





5.2 BASIC WORKSPACE-CONTROL COMMANDS 


This section describes the basic workspace-control commands, which 
allow the user to manipulate APZ workspaces in a variety of ways: 


e Clear and name the active workspace 


e Save the active workspace on a secondary storage device 
and retrieve it when required 


8 List workspace names 


e Delete workspaces or files when no longer needed 
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5.2.1 )CLEAR: Clearing the Active Workspace 
Format: J)CLEAR 


Example: ) CLEAR 
CLEGR WS 


The JCLEAR system command operates in action mode. It closes all open 
files and clears the active workspace by replacing it with a special 
workspace known as the elear workspace. There are a number of charac- 
teristics associated with this special workspace. The clear workspace: 
1. contains no functions, variables, or open files 
2. has an index origin of 1 


3. has an output line length of 72 


4. displays numbers with six (single-precision) or ten (double- 
precision) significant digits 


5. has a_comparison tolerance (fuzz) of 52 7 (single-precision) 
or 5F 15 (double-precision) 


6. has a clear symbol table and state indicator 
In RSTS/E systems, the file named SAPLCLR.APC is used to clear the ac- 
tive workspace. If this file cannot be found in the system, the APL 


session will immediately be terminated and control will return to BASIC, 
which will display the "Ready" message. 


5.2.2 J)WSID: Identifying the Active Workspace 


Format: JWSID [filename ] 
Examples: JWSTE BOLO (Names the active workspace) 
WAS CLEAR WS 
pee ale (Returns name of active work- 
BORO space) 


The )WSID system command may be used in both action and inquiry mode. 
As an action command, )WSID allows the user to change the name of the 
active workspace. As an inquiry command, the )WSID command returns 
the current name of the active workspace. The filename parameter is 
required in action mode, but the user need not specify all components 
of the workspace name (see Section 5.1.3). When parts of the name are 
omitted, the default values summarized in Table 5-1 are assumed. 


As illustrated in the examples above, the )WSID system command returns 
a workspace name in both action and inquiry mode. In inquiry mode, the 
name displayed is the current name of the workspace. In action mode, 
the name displayed is the workspace name before the user changed it by 
means of the J)WSID command. When )WSID returns a workspace name, it 
displays only the name, not the other parts of the filename. 
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5.2.3 JSAVE: Saving a Copy of the Active Workspace 


Format: )SAVE [filename] 


Examples: 

SAVE (Clear workspace cannot be 
MOT SAVED, WS IS CLEAR ws saved) ; 

J8AVE Boxe (Change name of active 
SAVED 44tO05t16 G-MAR~79 ROO workspace) 

SBOE (Save active workspace under 
BAVER 14t05¢27 BMAP BORE default name) 

JWEIT FCO Ra (Change name of active 
WHS FOZ workspace) 

BOVE (Save active workspace under 
SAVER L4¢O83 47 yoMak. 79 FOORaR  Gefault name) : 

WET EO (Change name of active 
Was FOORAF: workspace) 


(Duplicate of existing file 
cannot be saved unless the 
specified name is also the 
name of the active workspace) 






eT EAVES y 


The )SAVE system command is an action command that saves a copy of 

the active workspace on a secondary storage device. The saved 
workspace may be stored as a file in core-image format on disk, 

floppy disk, DECtape, or magnetic tape. If a filename parameter is 
included, )SAVE stores the active workspace under the specified name. 
If the filename parameter is omitted, )SAVE stores the workspace under 
the current name of the active workspace. In both cases, the default 
file extension is .APC. APL substitutes the default components 
described in Table 5-1 for any other missing filename components. 


APL does not allow the user to save the clear workspace (see the first 
JSAVE in the sequence of examples above). APL also attempts to pre- 
vent users from accidentally destroying saved files. If the filename 
specified in the )SAVEZ command is identical to the name of an existing 
file but different from the workspace filename of the currently active 
workspace, then APL refuses to save the workspace (see the last 
example above). 


The )SAVE system command responds to the user's specification by 
displaying the time and date. 


When a workspace is )SAVFd, the following values are preserved: 


e symbol] table 

e current contents of state indicator 
e value of index origin 

e output line width 

® number of significant digits 

e relative fuzz factor 

e current random number sequence 


All open files are closed automatically before the workspace is saved. 
Once a file has been saved in core-image format, it may only be re- 
trieved from secondary storage by the )LOAD system command (Sec- 

tion 5.2.4). 
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If the user saves the active workspace while a function is executing, 
the function will be interrupted before the )SAVE is performed. When 
the workspace is subsequently loaded, execution of the interrupted 
function will resume automatically. 


5.2.4 )LOAD: Retrieving a Workspace 


Format: JLOAD filename 
Examples: (Save active workspace) 
VSOaVE 8 TRE y F 
SAVED 74tagr So S-MAR.A79 STROF Y (Clear active workspace) 
SAT ° « 
PsA RS he (Reload file as active 


SLO SY RR works pace ) 


BAVED 14246259 5 MAR 79 


The /LOAD system command operates in action mode and retrieves a 
workspace from such secondary storage devices as disk, floppy disk, 
DECtape, and magnetic tape. The workspace that is loaded becomes 

the active workspace, replacing the currently active workspace. 

The workspace specified in the filename parameter must be a core- 
image file that was saved by means of a )SAVE command (Section 5.2.3). 
The default extension for the file being loaded is .APC. APL sub- 
stitutes the default components described in Table 5-1 for any other 
missing filename components. 


The )LOAD system command responds to the user's specification by 
displaying the word SAVED, followed by the time and date when the 
workspace was saved. 


5.2.5 )LIB: Listing Workspace Names (RSTS/E, RSX-11M, and IAS only) 
Format: )LIB [ftlename ] 


Examples: 


LIE 


,SAVE WS4] 
SAVED 15321234 §-MAR-79 W541 
LIE 
WOA] 


JLIE WS50,x 
W550, 
WS5Q,F EL 
WE50, VA 


YLIB COS,MAC 
COS ,MAC 


The )LIB system command operates in inguiry mode. It is used to 
display a list of workspaces in the user's disk area or selected 
files on any directory device. )ZIB assumes that any file in the 
user's disk area with the extension .APC contains a workspace. 
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The files displayed by )LIB need not be APL workspaces. If the 
filename parameter is included in the command, the user can 

specify the filename or category to be displayed. The filename 
specification can identify a particular file or can serve as a 
"wild-card" reference when an asterisk is substituted for the file- 
name and/or the file extension. The asterisk matches any name. For 
example: 


)ZLIB WS40.* 
will list the names of all files that have WS40 as their filename. 
Another example of this usage is shown in the third )LIB in the 
sequence of examples above. The command: 

)LIB DSKH:*.* 


will list the names of all files on device DSKH:. 


If the filename is omitted from the )ZIB command, all workspaces 
in the user's disk area will be displayed. 


5.2.6 )DROP: Deleting Stored Workspaces or Files 
Format: )DROP filename 


Example: 
SOO STR YT 
L4¢351704 Si MAR FY 





The )DROP system command operates in action mode and allows the user 
to delete from secondary storage the workspace or file identified in 
the filename parameter. )DROP can be used to delete any system file 
for which the user has the necessary protection privileges. A default 
extension is not supported for the )DROP command, so an explicit 
extension name must be supplied in the filename parameter. 


5.3 WORKSPACE-CONTENT COMMANDS 


This section describes the system commands that facilitate the 
examination of functions and variables in the user's workspace. The 
following operations can be performed: 


e Display a list of variables defined in the active workspace 
e Display a list of functions defined in the active workspace 
e Erase defined functions and variables 

e Display the APL state indicator to report on the execution 


of functions in the workspace. 
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5.3.1  J)VARS: Displaying a List of Global Variables 
Format: )VARS [letter] 


Examples: JVARS 
& AAA AEC E 

VARS 

A AAA ARC & 

VARS 


OC O SSE 


te 


tH 
hi 
nM 


99 bo 


VARS 


fi 


The )VARS system command operates in inquiry mode and displays an 
alphabetical list of names defined as global variables in the 
active workspace. The optional parameter specification identifies 
the letter at which the alphabetical listing is to begin. If 

the parameter is omitted, the entire set of global variable names 
is displayed. 


5.3.2 )FNS: Displaying a List of Functions 


Format: )FWS [letter] 
Examples JF MS 
DMO THS TR MME HUM WUMPUS 
JENS Me 


HUM WUMFUS 


The )FVS system command is an inquiry command. It displays an 
alphabetical list of global names used as defined function names 

in the active workspace. The optional parameter specification 
identifies the letter at which the alphabetical listing is to begin. 
If the parameter is omitted, the entire set of global function 
names is displayed. 


5.3.3 )GROUP: Defining or Dispersing a Group 
Format: )GROUP group-name [group-member-list] 


Examples: )GROUP FINANCIAL INTEREST FUTUREVAL PRESENTVAL 
)GROUP FINANCIAL 
)GROUP FINANCIAL TAX FINANCIAL 


The )GROUP system command operates in action mode. It is used to 
place a collection of named objects under one group name and to 
disperse an existing group. The objects may be variables, functions, 
and other group names. The )GROUP command is used primarily in 
conjunction with the )COPY and )PCOPY commands. After collecting a 
set of functions and variables under one group name, the user can 
specify this name in a )COPY or )PCOPY command in order to copy the 
entire collection at one time. In the first example above, the 
functions and variables named INTEREST, FUTUREVAL, and PRESENTVAL 

are collected under the group name FINANCIAL. 


In addition to its function in establishing a new group, the )GROUP 
system command can be used to disperse an existing group. If the 
group~-member-list parameter is omitted and only the group-name is 
included in the command line, then the named group will be dispersed. 
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The group name will no longer be defined, but the individual members 
of the group will be preserved under their original names. [In the 
second example above, the group named FINANCIAL is eliminated. The 
members of the group, INTEREST, FUTUREVAL and PRESENTVAL are 
unaffected. 


The )GROUP command can be used to add a new member to an existing 
group. To accomplish this task, the user specifies the group name 
itself as an element in the member list, as illustrated in the third 
example above. In this case, the function named TAX is added to the 
existing group named FINANCIAL. The following example illustrates 
another use of this feature. 


)GROUP GEOMETRY ANGLE ACUTE OBTUSE 
)GROUP GEOMETRY GEOMETRY PYTHAG ANGL1 ANGL3 


5.3.4  )GRP: Displaying the Members of a Group 


Format: )GRP group-name 
Examples: )GROUP ROOTS TRAPEZOID REGFALSI NEWTON SECANT 
)GRP ROOTS 
TRAPEZOID REGFALSI NEWTON SECANT 


The )GRP system command is an inquiry command used to display the 
members of the group named in the command line. The members are 
listed in the order in which they were entered into the group. 


5.3.5 )GRPS: Displaying a List of Groups 


Format: )GRPS [letter] 
Examples: )GRPS 
FINANCIAL RooTS 
)GRPS G 
ROOTS 


The )GRPS system command operates in inquiry mode and is used to dis- 
play an alphabetical list of global names used as group names in the 
active workspace. The optional parameter specification identifies 
the letter at which the alphabetical listing is to begin. If the 
parameter is omitted, the entire set of group names is displayed. 


5.3.6 )COPY: Copying Objects from a Workspace 
Format: )COPY filename (tnamed-object-list} 


Examples: )COPY MYWORK 
SAVED 9:43:10 93-OCT-75 


)COPY MYWORK EXAM A B REG 
SAVED 13:22:10 5-SEP-75 


JOOR TY MYWORK BYR 


HO SUCH FILE 
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The )COPY system command operates in action mode. It is used to 
retrieve functions, variables, and groups from a workspace called the 
copy workspace and to copy them into the active workspace. The user 
may copy all of the named objects in a workspace, or may copy only a 
subset. The named-object-list parameter can be used to identify the 
specific objects to be copied. If this parameter is omitted, all 
functions, variables, and groups in the workspace will be copied. 


)COPY does not have the effect of copying the workspace itself. Local 
variables, the state indicator, and the width, origin, and significant 
digit settings are not transferred. 


If objects in the copy workspace are homographs of (i.e., have the 
same name and characteristics of) objects in the active workspace, 
the objects in the active workspace will be replaced by their copy 
counterparts. However, homographs in the active workspace that are 
pendent functions or are functions in the process of being defined 
are not replaced. See the third sample command above for an example 
of a function of this kind. 


If a group name is included in the named-object list, then all of the 
members of the group are copied along with the group name. 


Named objects that cannot be found in the copy workspace or cannot be 
copied to the active workspace are displayed, as shown in the third 
example above. The format of the )COPY command response is identical 
to that of the )ZOAD command described in Section 5.2.4. 


5.3.7 )PCOPY: Copying from a Workspace with Protection 
Format: )PCOPY ftlename [named-object-list] 


Examples: )PCOPY MYWORK F PLUSROW PRIMES A 
SAVED 11:02:24 21-APR-75 
NOT COPIED: A 


)PCOPY MYWORK G BF 
SAVED 11:02:21 21-APR-75 
NOT FOUND: @G 


The )PCOPY system command operates in action mode. Its format is 
identical to that of )COPY, but it is used to protect functions, vari- 
ables, and groups in the active workspace from accidental destruction. 
Unlike )COPY, the )PCOPY command does not replace objects in the active 
workspace that are homographs of objects in the copy workspace. 


When copying groups, the )PCOPY command does not copy any members of 
the group that have homographs in the active workspace. If the group 
name itself has a homograph in the active workspace, then )PCOPY will 
not copy the group name but will copy all members of the group that 
do not have homographs in the active workspace. 


The format of the )PCOPY command response is identical to that of the 
)COPY (Section 5.3.6) and )LOAD (Section 5.2.4) commands. Named 

objects that cannot be found in the copy workspace or cannot be copied 
to the active workspace are displayed, as shown in the examples above. 
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5.3.8 JERASE: Erasing Global Names 
Format: JERASE name-ltst 
Examples: 


ae2 34 
a 

234 
BECEO 
JERASE A & 
A 


VALUE ERROR 
a 


t 
JENS 
Fy FQ 
Sz 
F2CL] 2 
F1C2) 
JERASE FY 
HOT ERASED? FY 
r3Q 
DT (Clear the state indicator) 
JERAGE Fy FS 
JENS 


The )ZERASE system command operates in action mode. It erases names 
from the active workspace by undefining the global functions and vari- 
ables specified in the name-list parameter. There may be any number 
of names in the list. The names must be separated by at least one 
space. 


JERASE may not be used to erase a function whose name appears in the 
state indicator (see Section 5.3.9). Examples of such attempts to 


erase pendent and suspended functions are included in the sequence at 
the beginning of this section. 


5.3.9 J)SI: Displaying the State Indicator 
Format: SI 


Example: 


yar 
TMBTRE 2] ox 
WUMFUSE 2] x 





The )SI system command is an inquiry command that displays the state 
indicator associated with the active workspace. The state indicator 
serves aS a report on the execution of functions in the workspace. 
By analyzing the )SI listing, the user can determine such function 
status conditions as the following: 


e pendent functions 


e suspended functions 
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e pending quad input requests 
e operations involving the execute operator 


The format of the )SI display line indicates the particular status 

of the function. A function name followed by a bracketed line number 
indicates that the function stopped at that line number. If an 
asterisk (*) follows the bracketed line number, the function is 
currently suspended. If the asterisk is omitted, the function is 
pendent, that is, awaiting a return from another function. 


The order in which function names are displayed in the )SI list is 
significant; the function that was most recently active is listed 
first. In the example included at the beginning of this section, 
WUMPUS called INSTR at line number [1]. Function INSTR was then 
suspended at line [3]. Execution of INSTR can be resumed by typing 


+d 


The state indicator also reports on pending quad input requests and 














pending execute operations (Sections 2.7.24 and 5.6). A quad input 
request is indicated by a quad character (0) in the )SI display 
line, and an execute request by an epsilon character («). Both of 


these conditions are illustrated in the example included below. 


eth (Execute an evaluated input) 
3 

184 (List the state indicator) 
{] 


Uys 
dh 


The use of the state indicator is discussed in terms of function 
execution in Section 3.4.4. 


5.3.10 J)SIV: Displaying the State Indicator and Local Variables 


Format: )SIV 


Examples: (Local variables B and I defined for 


& gen function IMAX) 
EV 
Sara: SE (Local variables A and B defined for 


sei function 2Z) 


EC] x A & 


The )SIV system command operates in inquiry mode. Like the )SI 
command (Section 5.3.9), it displays the state indicator associated 
with the active workspace and reports on pendent and suspended 
functions, pending quad input requests, and execute operations. In 
addition to this information, however, )SIV also displays a list of 
local variable names defined for each pendent or suspended function. 
The names of global variables used in the function are not displayed. 


5.4 WORKSPACE-ENVIRONMENT COMMANDS 
This section describes a variety of system commands that allow the 


user to display and control the characteristics of the workspace 
environment. These commands perform such tasks as the following: 
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® Specify the index origin setting 


e Specify the maximum number of significant digits to be 
displayed in APL output 


e Set the width of the output line 


e Set the fuzz or comparison tolerance 


5.4.1 JORIGIN: Determining the Index Origin 


Format: )ORIGIN ra 
Examples: 15 
Ie 2 3. 4 6 
JORIGIN 0 
WAS 1 
15 


o £ 2 F #& 


JORIGIN 


The )ORIGIN system command can be used in either action or inquiry 
mode. As an action command, )ORIGIN allows the user to change the 
setting of the index origin for array operations and returns the 
previous setting. In inquiry mode, the )ORIGIN command returns the 
current setting of the index origin. A parameter (0 or i) is 
required in action mode. The default setting is l. 


The effect of the )ORIGIN system command is to renumber the elements 
of arrays to begin at zero or one, depending on the index origin 
setting. This command is particularly relevant when used in conjunc- 
tion with the APZ iota operator (Sections 2.7.5 and 2.7.6)for a 

more detailed discussion of the index origin, see Section 2.4.2. 


JORIGIN is equivalent to the OIO system variable (Section 4.2.2). 
The index origin setting is preserved when the active workspace is 
saved. 


5.4.2 )DIGITS: Determining the Output Precision 
Format: JDIGITS [n] 


Examples: )DIGITS 
z 
B 
1.234567 


YDIGITS 3 
WAS 7 

B 
1.23 
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The )DIGITS system command operates in either action or inquiry mode. 
As an action command, )DIGITS can be used to specify the maximum 
number of significant digits to be displayed in APZ output; 

it returns the previous maximum number. In inquiry mode, the 

)DIGITS command returns the number of significant digits currently 
being displayed. A parameter must be included in action mode to 
specify the number of significant digits to be displayed. The 
default number of digits is 10 for double-precision systems and 6 for 
single-precision. Legal values are integers in range 1 through 17 
for double-precision systems and 1 through 7 for single precision. 


The )DIGITS system command does not affect the precision of internal 
calculations or the display of numeric constants. See Section 2.2 
for an example of formatting numeric output. 


)DIGITS is equivalent to the OPP system variable (Section 4.2.3). 
The precision setting is preserved when the active workspace is 
saved. 


5.4.3  )WIDTH: Determining the Width of the Output Line 
Format: )WIDTH [n] 


Examples: )WIDTH 50 
WAS 120 
115 
42 3 8 5 € 7 8 8 20 Ti 42 4293 %s4 2S 


)WIDTH 30 
WAS 50 
115 
a; 2 3 4 iS 6 7 8 9 
10 11 12 £3 14 15 


)WIDTH 
30 


The )WIDTH system command can be used in either action or inquiry 
mode. As an action command, )WIDTH allows the user to set the 
maximum number of characters that may appear in an output line and 
returns the width previously in effect. In inquiry mode, the 
)WIDTH command returns the current width of the output line. The 
nm parameter must be included in action mode to specify the maximum 
number of characters in the output line; it must be an integer in 
range 30 through 133 inclusive. The default setting is 72, except 
in the RSTS/E environment, in which APL defaults to the current 
user width. 


The )WIDTH system command does not affect the display of messages 

on the terminal or the allowable length of input lines. )WIDTH is 
equivalent to the OPW system variable (Section 4.2.4). The width 

setting is preserved when the active workspace is saved. 
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5.4.4 )FUZZ: Determining the Comparison Tolerance 
Format: JFUZZ ([n] 


Examples: 


The )FUZZ system command operates in either action or inquiry mode. 
In action mode, it changes the APL relative fuzz or comparison toler- 
ance. As described in Section 2.4.3, relative fuzz is the tolerance 
used in comparing two numbers to determine whether or not they are 
close enough to be considered equal. The )FUZZ command changes the 
APL comparison tolerance to the value of n and returns the previous 
fuzz setting. In inguiry mode, )FUZZ returns the current comparison 
tolerance. m must be in the range of 0<ns< approximately .38. The 
default fuzz setting in the clear workspace is 5F 7 for single- 
precision versions of APL and 5EF 15 for double-precision versions. 


The )FUZZ command is equivalent to the OCT system variable (Sec- 


tion 4.2.1). The current fuzz setting is preserved when the active 
workspace is saved with the )SAVE command. 


5.5 APL TERMINATION COMMANDS 


This section describes the system commands used to terminate the 
current APL session. The user can exit from APL in two ways: 


@ Terminate the APL session 


e Terminate the session and run a program 


5.5.1 JOFF: Terminating the APL Session 


Format: ) OFF 
Examples: ) OFF (RT-11M) 
) OFF (RSTS/E) 
Ready 
) OFF (RSX-11M) 
> 
) OFF (IAS) 
PDS> 


The )OFF system command is an action command that terminates the 
user's APL session. All APL sessions should be concluded with an 
)OFF command, a )RUN command (Section 5.5.2), or I-beam 36 
(Section 4.3.15). When an )OFF command is executed, the current 
active workspace is lost. 
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As illustrated in the examples above, the APL user returns automati- 
cally to system command level after issuing an )OFF command in the 
RT-11 operating environment. RSTS/E users return automatically to 
BASIC, which displays a "Ready" message. RSX-11M users return to MCR, 
which displays an angle bracket (>).IAS users return to PDS. 


If an LA36 or Tektronix 4013/4015 user has selected the APL charac- 
ter set for use during the current session, special escape characters 
are transmitted to cause the terminal to switch to the ASCII 
character set when the APL session terminates. 


5.5.2 )RUN: Terminating the Session and Running a Program 
Format: )RUN filename 


Example: 
JRUH Loge MUM BLE (RT-11) 
LLidl4ar 32 1oO-AaAuG.7y9 


FUR FOO, & 


(RSTS/E) 
L4iQ7iS4 9-AUG.79 





The )RUN system command operates in action mode. It terminates the 
current APL session as )OFF does, and returns control to system com- 
mand level in RT-11 and to BASIC in RSTS/E. It then runs the program 
specified in the filename parameter. The specified file must contain 
a program that is ready to run. Control does not return automatically 
to APL after the specified program has been executed. 


The )RUN command does not save the currently active workspace before 
terminating the APZ session, so the user should be aware that the 
active workspace will be lost. If the program identified by ftle- 
name cannot be found, APZ will display the message: 

FILE NOT FOUND 
in the RT-11 system, and 

CAN'T FIND FILE OR ACCOUNT 
in the RSTS/E system. 


This command has no meaning in RSX-11M and IAS environments. 


5.6 SYSTEM COMMANDS AND THE EXECUTE OPERATOR 


The APL execute (c«) operator allows any system command to be used as 
its operand. The value returned by « is always a character vector; 


when displayed, this response resembles the response of the command 
itself - for example: 


He 
Xs 4 


Hee | VARS 


ey E 
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The use of the execute operator allows system commands to be invoked 
from within an APL function. The following example illustrates a 
function that stores the names of all global variables in the active 
workspace and then lists them on the terminal. 


The shape of the result returned by the execute operator after 
executing a system command indicates the number of characters in 
the command response. The carriage return/line feed characters 
output by an execute operation are included in the count. The 
following illustrates several examples of execute values, with 
comments describing the characters included in the count. 


Meg | VORTE TH 1 


a 
WAS O 
; ro Shape is 7: string 'WAS 0', carriage 
? return, line feed 
Aee  PWEOTH PAS! 
x) 
WAS 5O 
ae Shape is 8: string 'WAS 50', carriage 
8 return, line feed 
Aeg  YBD 
io) 
ra Shape is 3: string 'e' (in state 
3 indicator), carriage return, line 
feed 
Meg | VERS ! 
tr 
ray 
pe Shape is 3: string 'A' (in variable 
4 list, carriage return, line feed 


The following example illustrates the use of the execute operator 
in setting the output line width and displaying a list of functions 
in the system. 


e132 

e')WEETH by ye 
WAS 132 

eg FNS? 


ge VARS! 
a 


Section 2.7.24 describes the APL execute operator in detail. 


CHAPTER 6 


THE FILE SYSTEM 


6.1 OVERVIEW OF THE APL-11l FILE SYSTEM 


APL-11 supports a powerful file system that allows the APL user to 
access source programs and data files on a variety of system devices, 
including disk, floppy disk, DECtape, and magnetic tape. The file 
system is implemented as an integral part of the APZ language and pro- 
vides an interface to the RT-1l, RSTS/E, RSX-11M, and IAS operating 
systems. 


The APL-11 file system has been designed in two components: 
e file operators for byte pointer, input, and output functions 


e system commands for use in assigning, creating, closing 
and renaming files 


File operations may be specified for files associated with any of 12 
channels, numbered 1 through 12; channel 0 is reserved for the user's 
terminal. This chapter describes in detail the use of the file opera- 
tors and system commands implemented for APL-ll. 


APL-11 supports two types of files: 
e ASCII sequential 
e random access 


The following subsections summarize the characteristics of these file 
types. 


6.1.1 ASCII Sequential Files 


APL ASCII files are sequential files that can be read and written by 
APL, by the PDP-11 MACRO Assembler, and by a variety of other language 
processors. ASCII files may also be created and modified by most of 
the text editors available under RT-11, RSTS/E, RSX-1l, and IAS. The 
format of the ASCII files created by BASIC and FORTRAN must be modified 
before these files can be processed by APL. 


6.1.1.1 ASCII Files Under RSTS/E and RT-11l 


ASCII format is line-oriented; each line of the file is terminated by 
a carriage return/line feed combination. If source lines or data 
values are read and written sequentially, this carriage return/line 
feed pair is inserted automatically at the end of each line. In APL, 
an ASCII file must be terminated by a CTRL/Z character, indicating an 
end-of-file condition. 


THE FILE SYSTEM 


To write this character explicitly, the user first positions the file 
pointer (see Section 6.2.1) at the character just past the last 
character of the existing file. If the CTRL/Z character is omitted 
from the file, the portion of the block past the end of the user's data 
will be read along with the last block of data. Blocking the APL 

ASCII files is standard. 


ASCII files contain only ASCII characters. If a user workspace has 
been created on a terminal that supports APL mode, any APL symbols 
entered in the file will be converted to keyword mnemonics before 
being saved in ASCII format. Because ASCII files contain no special 
APL characters, they can be displayed directly on terminals and high- 
speed printers that may not support the APL character set. 


6.1.1.2 ASCII Files Under RSX-11 and IAS 


ASCII format files under RSX-11 and IAS are handled as variable length 
records which may not span blocks (512 bytes). To create or access an 
ASCII file the )CREATE or )ASSIGN commands (described in Section 6.3.1 
and 6.3.2) are used with the /FA switch. This switch must be present 
after the filename in order access an ASCII file. The /-FA form may 
be used with random access files. If the switch is omitted then a 
random access file is assumed. An existing ASCII file may be accessed 
as a random access file; however, the user will need to be familiar 
with FCS internal formats. 


6.1.2 Random-Access Files 


Random-access files may be read and written in a non-sequential fash- 
ion and may be used to store and access data in several different 
formats. 


In random-access mode, the APL user treats a file as a random-access 
memory. Before reading or writing a single byte or a data value, the 
user positions the file pointer at the appropriate location in the 
file by the set pointer operator (ff, see Section 6.2.1). The file 
pointer must always be positioned at the byte just before the next 
byte to be read or written. After each read or write operation, the 
file pointer is advanced automatically to point to the next byte or 
data value in the file. 


When the user positions the file pointer and reads or writes a data 
value in random-access mode, he must specify the type of data being 
accessed. The data types summarized in Table 6-1 are supported by 
APL-1l1. The code in the type column is used in the file pointer, 
input, and output functions (Section 6.2). 


If the type code is omitted from a file operation, APL assumes that 
the data is ASCII sequential (type 0). All of the data types 
identified in Table 6-1 are compatible with the storage of BASIC- 
PLUS virtual arrays and with FORTRAN direct-access files. 


The use of random-access mode facilitates the storage of values in 
mixed data formats and the construction of records containing several 
different types of values. For example, the user may construct a 
series of records, each consisting of a byte value, followed by an 
integer, followed by a line of character data, and concluded by a 
floating-point array. When accessing the individual components of 
these records, the user simply identifies the relevant data type. A 
read operation performed on an integer causes two types of data to 
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Table 6-1 
APL-11 Data Types 





ha 


1 byte 
al 


1 byte 















ASCII sequential; character data 
processed a line at a time. 


Byte; numeric quantities in range 
0 through 255 












Integer; numeric quantities in 
which pairs of bytes are processed 
as 16-bit integers 





APL internal format; character data 
in internal format, one character 

per byte; carriage return/line feed 
is not inserted automatically at the 
end of each line of data 

















Single-precision floating-point; 
numeric quantities in which one 
single-precision number is processed 
as a four-byte value 






Double-precision floating-point; 
numeric quantities in which one 
double-precision number is processed 
as an eight-byte value 


be read. A write of a single-precision floating-point number causes 
four bytes of data to be written. Because all values are actually 
transferred in byte format, the APL-11 user need not be concerned with 
aligning numeric data along word boundaries. 


If the user issues a file output operation, APL attempts to convert 
the value being written to the data type specified in the file opera- 
tor. In some cases, conversion is impossible - for example, from a 
character matrix to a double-precision number, or vice versa. 
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6.2 FILE SYSTEM OPERATORS 


Three APL-11 file system operators have been implemented to perform 
the following functions: 


® set a pointer to a specific byte or data value in the 
file (ff) 


® read one or more data values from a file (4) 
e write data into a file (BA) 


The file operators are constructed by overstriking the APL quad char- 
acter (0) with the up-arrow, left-arrow, and right-arrow, respectively. 


When the user issues a file I/O operator, he must normally specify: 


® the channel number associated with the file to be read or 
written (an integer expression in range 1 through 12) 


® the data type of the value to be read or written (an integer 
constant in range 0 through 5, enclosed in square brackets) 


¢ for input/output, the number of values to be read/written 


Because the APL-1l1 file operators refer to channel numbers rather than 
to actual filenames, the user may construct programs that are relative- 
ly filename-independent. 


When the user specifies a file read or write operation, APL will trans- 
fer data beginning at the byte at which the file pointer is currently 
positioned. If random-access file operations are being performed, the 
user should be careful to issue a set pointer function before invoking 
the desired read or write operation. 


This section describes the functions of the file pointer, file input, 
and file output operators and provides examples of their use. 


6.2.1 fi: Setting the File Pointer 


Format: channel-number & [type] W 
. 6HC27100 (Set the file pointer to byte 200 on 
ExemEes 100 channel 6; each integer value is two 
bytes long) 
Lid (Request the current value of the file 
257 pointer on channel 1; file pointer is 


now set at byte 257) 


1m71 (Request the length of the file on 
10241 channel 1; file is now 10241 bytes 
long) 


The set file pointer operator is used to: 
e move the pointer to a specific location in a file 
® return the current location of the file pointer 


® return the length of the file 


6-4 


THE FILE SYSTEM 


The file pointer identifies the byte at which the next file read or 
write operation is to begin. It always points to the next byte to be 
read or written in the file associated with the specified channel- 
number. The value of channel-number must be an integer in range 1 
through 12. The type argument identifies the data type of the value 

to be read or written in the file. W identifies the byte or data 

value at which the pointer is to be positioned. The following examples 
illustrate the use of the set pointer function in positioning the 
pointer in the file. 


To move the pointer explicitly to byte 100, the user specifies a func- 
tion of the following format: 


14#[1]100 
100 


A type of 1 indicates that the file contains byte values. If a file 
consists of double-precision floating-point numbers, the user might 
set the pointer at byte 80 by specifying the following: 


14[5]10 
10 


This second approach causes APL to multiply the number of values (10) 
by the length in bytes (8) of the specified data type (double-preci- 
sion floating-point) and to position the pointer at byte 80 for the 
next read or write operation. Note that because these file pointer 
functions do not contain explicit assignments, the new value of the 
file pointer is displayed at the terminal. 


If the type parameter is omitted from this version of the set pointer 
function, data type 0 (ASCII) is assumed. For RSX-11 and IAS, the 
user cannot set the pointer on ASCII files. 


The set pointer operator may also be used to perform two query func- 
tions. If the W argument is negative, the current value of the file 
pointer is returned as shown below. 


1M[1] 1 
74 


The value returns in units of the specified data type. 


In a query function of this kind, the W value may be any negative num- 
ber; the particular value is not significant, only the sign. A non- 
zero type argument must be supplied to indicate the data type. 

Table 6-1 summarizes the data types supported by APZ-11. For RSX-11l 
and IAS files, the position is given in records or lines. 


The second pointer query function allows the user to determine the 
length of the file. If the type parameter is zero or omitted, the 
length of the file associated with the channel-number is returned in 
bytes. A negative value must be supplied for the NW argument; the 
particular value is not significant, only the sign. The maximum file 
size is 65K blocks. All of the following pointer functions are 
equivalent: 


2H[0] 1 
5121 _ 

2H[0] 200 
5121 | 

28 1 
5121 
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The file pointer setting depends upon the current value of the index 
origin (Sections 2.4.2 and 5.4.1). If the index origin is set to one, 
the first pointer position in the file is also one; if the value of 
the index origin is zero, the first file pointer position is zero. 


The value of the file pointer is updated automatically after each file 
input or output operation. If the user is reading or writing sequen- 
tially, he need not set the pointer each time he specifies an input 

or output operation, because the pointer advances automatically through 
the file. As mentioned in Section 6.1.1, however, he must insert a 
CTRL/Z character at the end of an ASCII sequential file to indicate 

an end-of-file condition. 


6.2.2 : Reading Data from a File 


Format: channel-number 4 [type] W 


Example: (Read 10 integers from 
channel 2, display on the 
2BL27 10 terminal) 


123545 67 8 8 19 


The file input operator reads one or more data values from the file 
associated with the specified channel-number. The number of values 
to be read is represented by W, and type identifies the type of data. 
Table 6-1 summarizes the data types supported by APZ-11. If the type 
parameter is omitted from the file input function, data type 0 (ASCIT) 
is assumed. 


The data type specified by the user determines the size of the input 
values being read. For example, integer data (type 2) is read as pairs 
of bytes. In the example at the beginning of this section, 10 inte- 
gers (20 bytes) are read from the file associated with channel 2. 
Because no explicit assignment is included in the file input state- 
ment, the integers are displayed on the terminal. The following ex- 
ample reads six integer values (type 2) from channel 2, and stores 
them in 4A. 


AG QHL2] 6 


Double-precision floating-point values (type 5) are read in groups of 
eight bytes. The input operator: 


7ACSIS 
12345 6 
reads six double-precision numbers, totaling 48 bytes, from the file 
associated with channel 7, and displays them on the terminal. 


When ASCII data values (type 0) are processed, APL reads the number 
of characters specified in the operator, unless it encounters the end 
of line first. A single file operator can never read more than one 
line of ASCII data at a time. Excess characters are ignored. 


Data values are read from the specified file, beginning at the byte 
indicated by the current value of the file pointer. The file pointer 
value is updated automatically after the transfer of data from the 
file has been completed. 
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6.2.3 H: Writing Data into a File 
Format: channel-number & [type] data 


Example: (Write an array of inte- 
2AC21% gers (X) on channel 2, 
12345 6789 10411 12 display on the terminal) 


The file output operator is used to write datainto the file associated 
with the specified channel-number. The type of data being written is 
specified in type, and data represents the data value or array to be 
output. If the type parameter is omitted from the file output func- 
tion, data type 0 (ASCII) is assumed. 


As in the file input function, the data type specified by the user 
determines the size of the values being written. For example, single- 
precision floating-point numbers (type 4) are written in groups of 
four bytes. In the example included at the beginning of this section, 
array X, consisting of 12 integer values (24 bytes) is written into the 
file associated with channel 2. Because no explicit assignment is in- 
cluded in the file input statement, the array is also displayed on the 
terminal. 


The output operator: 

SAL4aIT 
1560944 1.79176 1.94591 2.07944 2.19722 2.30258 2.3979 2.48491 2.56495 2.43906 
writes ten single-precision floating-point numbers, totaling 40 bytes, 
on the file associated with channel 9, and displays them on the ter- 
minal. 


Data values are written on the specified file, beginning at the byte 
indicated by the current value of the file pointer. The file pointer 
value is updated automatically after the transfer of data to the file 
has been completed. 


6.2.4 File Operator Examples 


The following example illustrates a simple use of the file pointer, 
input, and output operators. 


FAC 272 (Write array of integers) 
123456789 10 11 12 13 14 15 

PHL 2I1 (Set file pointer to integer 
1 value 1) 

GALL2I12 (Read 12 integer values; 
12345 6789 10 11 12 display on terminal) 

SAC 271 (Set file pointer to integer 
1 value 1) 

SAL216 (Read 6 integer values; 
12345 6 display on terminal) 


The next example illustrates the use of the file operators in two 
user-defined APL functions. In this example, the GFT function is used 
to read records from the file associated with channel 7. The PUT 
function writes records on that file. Each record is 17 bytes in 
length and has the following format: 


Variable Name 
A 
B 


Cc 


D 


Note that line 5 of the PUZ function a 
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Data Type 
(byte) 
(integer) 


(double-precision 
floating-point) 


(APL format: six- 
character literal 
vector) 


the length of D is less than six bytes. 


v GET M 32 


C1] Se 7MCL I+, 7xn-1 


C2) Ae7BCi 1 

C3] Be7Al2d1 

C4) Ce7BCSI1 

CSI De7Al 316 
v 


Vv FUT N 32 


C17 7MCLIL+L 7 xh 


C27] *¢7HC1iI4 
C3] *¢7HC 21% 
C4] 2¢7ACS Ic 


CS] *¢7AC 31640 


v 

A 
1 

& 
27 

c 
1.6 

rn 
AEBRCIEF 

FUT 5 
59 

ACKECEeLE PO 

GET & 

a 
1 

& 
27 

Cc 
1-6 

ba) 
ABCDEF 


Length in Bytes 
1 
2 
8 


ppends blanks to variable D, if 
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6.3 FILE SYSTEM COMMANDS 


This section describes the system commands implemented for use with 
the APL-11 file system under any of the supported operating systems. 
These commands are used to: 


e assign files 

® create new files 
e close files 

® rename files 


Because these are APL system commands, the command formats and use of 
parameters are consistent with the descriptions included in Chapter 5. 
In particular, the filename format discussed in subsequent sections 

is identical to the filename format associated with workspace names 
and described in Section 5.1.3. 


As illustrated in Chapter 5, an RT-1l filename consists of the 
following components: 


device:name.extlsize] 
A RSTS/E filename may have several additional components: 


device:name,ext<prot>(prj,prg1/SIZE:stze/CLUSTER:clus/MODE: 
mode(/SI(ZE]:26) 


In RSX-11M and IAS systems, filename has the following format: 
devtce:(UIClname.ext;verston 


If any system-specific filename components are included in an file 
specification for another system, the command will be ignored or an 
error message given. 


In the RSTS/E system, a filename of the form: 
$name 


identifies a file called name, located in the disk area associated 
with project-programmer number [1,2] (the system library). This 
format is used in several of the examples included in this section. 
The meanings of the other special characters that may be included in 
the filename are summarized in Table 5-1. If one of these special 
name formats is included in an file specification for another system, 
the special character will be ignored. 


A channel-number argument must be included in most of the system 
commands described in this section. This is an integer constant in 
Yange 1 through 12; it may not be a variable or an expression. For 
RT-11 files, the channel-number argument is the same as the RT-11 
channel number. 
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6.3.1 JASSIGN: Assigning a File 
Format: J)ASSIGN channel-number filename [/FA] 


Examples: 
JASSIGH % UTILTY, AFL 


JASSIGH 9 C1LOOrs 144] WUMFUS, FL. 


The )ASSIGN system command assigns an existing file to a specified 
channel-number. It associates the filename identified in the command 
line with the number of the channel referenced in the assignment, and 
effectively opens the file for input or output. The ehannel-number 
must be an integer constant in range 1 through 12, and the filename 
must conform to the naming conventions described in Section 5.1.3. 

If an extension is omitted from the filename, the default extension 
is .APL. 


The /FA switch is for use with RSX-11 and IAS systems only. It indi- 
cates that an ASCII sequential file is to be assigned. If omitted, 
or if /-FA is specified, than a random access file is assumed. An 
ASCII file may be assigned for random access. 


The )ASSIGN command does not cause any input or output to be performed 
It simply establishes a connection between a file and a channel 
number. 


JASSIGN is used only for files that have already been created on a 
channel. If the user wants to open a new file for output, he must 
issue a )CREATE command (Section 6.3.2) for that file. If an )ASSIGN 
command is specified for a channel that is already associated with an 
open file, APL automatically closes the assigned file before opening 
the new file. A maximum of 12 files may be open at any one time in 
the APL system, on channels 1 through 12. 


If APL cannot find the filename referenced in the )ASSIGN command, 
it displays one of the following error messages, depending upon the 
operating system being used. 


FILE NOT FOUND (RT-11) 
CAN'T FIND FILE OR ACCOUNT (RSTS/E) 
FILE NOT FOUND (RSX-11M) 
NO SUCH FILE (IAS) 
6.3.2 )CREATE: Creating a File 
Format: )CREATE [ehannel-numberlfilename /FA 


Examples: 


JCREATE TMF O20, TMF 
JCREATE | FOO, BAT/SIZE¢3 


The )CREATE system command creates a new file on a specified channel- 
number. It associates the filename identified in the command line 
with the number of the channel referenced in the command, and opens 
the file for subsequent input. The channel-number is optional; 

if it is included, it must be an integer constant in range l through 
12, and the filename must conform to the naming conventions described 
in Section 5.1.3. If an extension is omitted from the filename, the 
default extension is .APL. 
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The )CREATE command does not cause any input or output to be performed. 
It establishes a connection between a file and a channel number, and 
it allocates a specified amount of space on the device associated with 
that channel number. The size of the file is included in the filename, 
enclosed in square brackets, as illustrated in the examples at the 
beginning of this section. Under RT-11l, RSX-11M, or IAS, any space 
allocated in the command but not filled as a result of writes will be 
deallocated. 


In the RT-11, RSX-11M, and IAS operating systems, if the ehannel- 
number argument is omitted from the )CREATE command, the file will be 
created but then closed, resulting in a zero-length file. Under 
RSTS/E, if the channel-number is omitted, the file is created and 
closed, but the space is not deallocated. 


The /FA switch is for use with RSX-11 and IAS systems only. It 
indicates that an ASCII sequential file is to be assigned. If omitted, 
or if /-FA is specified, then a random access file is assumed. 


)CREATE is used only when the user is creating a new file on a channel. 
The )ASSIGN command (Section 6.3.1) must be issued to open an existing 


file. A file must be either )CREATEA or )ASSIGNed before it can be 
read or written by APL. 


6.3.3 J)CLOSE: Closing a File 

Format: J)CLOSE channel-number 

Example: J)CLOSE 3 
The )CLOSE system command closes the file currently associated with 
the specified channel-number and effectively deassigns the file on 
that channel. The channel-number must be an integer constant in range 


1 through 12. 


When APL closes a file on a channel, it automatically performs the 
following operations: 


e writes any pending output to the file before closing it 
e deallocates any internal buffers associated with the file 
The )CLOSE command is used to close the file on a single channel. 


There are a variety of APL system commands that cause all open files 
in the user's system to be closed automatically. These are: 


ce) ) CLEAR (Section 5.2.1) 
e )SAVE (Section 5.2.3) 
e ) LOAD (Section 5.2.4) 
e ) OFF (Section 5.5.1) 
e )RUN (Section 5.5.2) 
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6.3.4 )RENAME: Renaming a File 


Format: )REWNAME filenamel filename2 
Example: 
JREHAME [TLE 0EMO APL TYE CEMOX, AFL. 


The )RENAME system command changes the name of a file from filenamel 
to filename2. The filenames specified in the command line must 

conform to the naming conventions described in Section 5.1.3. If an 
extension is omitted from a filename, the default extension is .APL. 


In the example included at the beginning of this section, the name of 
the DECtape file, DEMO.APL, is changed to DEMOX.APL. After the rename 
operation has been performed, the old name is no longer available. 
This is illustrated in the expanded example below. 


APPENDIX A 


SUMMARY OF APL FUNCTIONS AND OPERATORS 


Table A-1 
Primitive Scalar Monadic Functions 


Section 
Function Meaning Reference 













- negative of Y 


magnitude of ¥ 


| Bineticn'oe 1et¥ecrinoneintesrat | 2.6 | 
function of Y+1 for non-integral Y) 2.6 





SUMMARY OF APL FUNCTIONS AND OPERATORS 


Table A-2 
Primitive Scalar Dyadic Functions 


jeenceson | naming | hee 
Function Meaning Reference 
X+Y 2.6 
X*Y 6 







_ay_—=iéds divide vy yOOC~“~*~*~*~rSCS~=‘ CS 
[aey | 4 to the veh power —OSSC~“~dSC“‘( 
X residue of Y 2.6 

maximum of X and Y 













Xi. binomial coefficient (number of 
combinations of Y things taken 
X at a time) 


Xoy trigonometric functions (Y is in 
radians) (see Table A-3) 2.6 






Table A-3 
Primitive Dyadic Circle Functions 


[_amanes [i SC—C~d 


(14+Y¥*2)*0.5 





















2 
| 
a 





SUMMARY OF APL FUNCTIONS AND OPERATORS 


Table A-4 
Logical Functions 


The following functions return 1 if the relationship is true, 0 if 


it is false. 
Section 

Function Meaning Reference 
f lose then 7 2.6, 2064 
X less than or equal to Y 2.6, 2.6.4 
X greater than or equal to Y 2.6, 2.6.4 
X greater than Y 2.6, 2.6.4 

4 














a 









SUMMARY OF APL FUNCTIONS AND OPERATORS 


Table A-5 
Primitive Mixed Functions 


Section 
Function Meaning Reference 


7 
7 


3 
~4 
vy generate the first Y consecutive 
integers from current origin 2.7.5 
XY find the first occurrence of Y 
within vector X 2.7.6 
ae 
X,Y 















return the ravel of Y (make Y a 
vector) 


Gah. 
catenate X to Y along the last 
dimension of X 2.7.8 
X,CWly laminate X to Y along the Nth 
dimension of X 2.7.8 
Y X (logical) compression along 
the last dimension of Y 2.7.9 
X/CNJY X (logical) compression along 
2.7.9 
Y X (logical) compression along 
the first dimension of y 2.7.9 
Y X (logical) expansion along 
the last dimension of y 2.7.10 
X\CNIJY X (logical) expansion along 
the Nth dimension of Y 2.7.10 
Y 
Y 
Y 
of Y 


X/ 
X# 
X\ 
xs 
Xt 
Xt 
for X<0, drop last |X elements 
Y 









the Wth dimension of y 

















X (logical) expansion along 
the first dimension of Y 
for X>0, take first X elements 
of Y 

for X<0, take last |X elements 
of Y 


for X>0, drop first X¥ elements 


















2.7.11 


2.7.12 


2 













" ([é 
Q transpose the dimensions of Y 
(for a matrix, exchange the rows 
and columns) 7.13 


transpose array Y according to X 2.7.14 
oy reverse along the last dimen- 
sion of Y 2.7.15 


oCwly reverse along the Nth dimen- 

sion of yY 2.7.15 
ey reverse along the first dimen- 

sion of Y 2.7.15 
Xoy rotate by X along the last dimen- 

sion of Y 2.7.16 
XoCWIyY rotate by X along the Nth dimen- 

sion of Y 2.7.16 


A-4 












SUMMARY OF APL FUNCTIONS AND OPERATORS 


Table A-5 (Cont.) 
Primitive Mixed Functions 


Section 
Function Meaning Reference 
rotate by X along the first 
dimension of Y 2.7.16 
generate an index vector such that 
YCAY] is in ascending order 2.7.17 
generate an index vector such that 
YCVYY] is in descending order 2.7.18 
roll an integer selected randomly 
in range 1 through Y (scalar 
function) 2.7.19 
deal X integers selected randomly 
in range 1 through Y without 
duplication 2.7.20 
tion to a character string consist- 
ing of the lines of Y separated by 


for numeric Y, convert to a char- 2.7.21 
acter string 

for character string Y, if Y is 

not a variable or function name, 
carriage-return/line-feed pairs 































return the null vector; if Y isa 

variable, convert the value of the 

variable to a character string; if 

Y is a function, convert the func- 
encode Y in number system X 2.7.22 
decode the representation of Y 
in number system X 2.7.23 
execute the character string Y 2.7.24 
determine the membership of X 
in array Y 2.7.25 


eliminate duplicates in set Y 2.7.26 
determine the union of sets, | ae. 
and Y 2.7.27 


Xny determine the intersection of sets, 
X and Y 2.7.28 
exclude elements that are in set X 
but not in set Y ols 
oa determine whether X is a subset 
of Y 


determine whether X is a superset 
of Y 





SUMMARY OF APL FUNCTIONS AND OPERATORS 


Table A-5 (Cont.) 
Primitive Mixed Functions 


Section 
Function Meaning Reference 
format character array Y 2.7.32 


ae er 
width and precision specified by Xx 2.7.33 


perform matrix division, solve 
linear equations, find a least 
squares solution 2.7.35 






SUMMARY OF APL FUNCTIONS AND OPERATORS 


Table A-6 
Composite Operators 


In the following examples, the character a stands for any primitive 


scalar dyadic function. 
Generalized Reduction and Scan 


Section 
Operator Meaning Reference 
a/Y the a reduction along the last 2.8.1 
dimension of Y 
a/CNIY the «a reduction along the Nth 2.8. 
dimension of Y 
afY the a reduction along the first 2:0aL 
dimension of Y 


a\Y the a scan along the last 2.8% 


dimension of Y 


a\CWIY the a scan along the th 2.8. 
dimension of Y 

akY the a scan along the first 2.8. 
dimension of Y 


Inner and Outer Products 


Section 
Operator Meaning Reference 


Table A-7 
eee 
aaeee 


Keyboard I/O Operators 
Section 
xX+O 







































quad (evaluated) input from 2.5.1 
keyboard 


5 
Rall 








quote-quad (character) input from 
keyboard, up to but not including 
carriage return 






quad-del (unedited) input from 
keyboard 





quad output (display value of X) 





SUMMARY OF APL FUNCTIONS AND OPERATORS 


Table A-8 
File I/O Operators 


‘ Section 
Operator Meaning Reference 
channel-number®ltypeIlN set file pointer 
channel-numberl type IN file input 


channel-numberB[ type ldata file output 6.2.3 















The arguments in the file operators have the following meaning: 


channel-number is the channel (1-12) on which the file is assigned 


N is the file byte or value referenced by the pointer, 
or the number of values to be read 

data is the value(s) to be written 

type is a code representing the type of data values and 


must be one of the following: 


ASCII sequential 

byte 

integer 

APL internal 

single-precision floating-point 
double-precision floating-point 


Oe&®WNHErO 


File and data types are described in detail in Chapter 6. 


Table A-9 
Primitive Mixed Functions and Operators 
(Summary Information) 

























monadic rho | dyadic rho | monadic iota monadic ravel | dyadic catenation 


(p) 


dyadic iota 
(1) 
R<X1Y 


Function 



















left non- 
Argument negative 
Domain integers 


right 











left 
Argument 
Shape 


vector 
(ppX<1) 














scalar or 
l-element 
vector 
















right 
non- 
negative 


Result 
Range non-negative] right 
integers argument integers 
vector array vector scalar or 
Result for a array 
Shape vector: 
oRh<>ppY poR<>X oR<>,Y 


Take 
Dimension 
Argument? 


Origin 

Dependent? 
Section 
Reference 


*Both arguments must be either character or numeric; argument types cannot be mixed in the same function. 


non-negative 
integers 















array 
oR<+>((K-1)+pX) ’ 
((pX)CK1+(pY) 

[K]),KypXx 











OT-WV 


Function dyadic 
compression 
(/) 
R<«X/CKIY 


Booleans 
(0, et 


left = or 
Argument vector 
Shape 
scalar or 
array 
dimension 


right 


Result 
Range 


Result 
Shape 


Take 
Dimension 
Argument 


Origin 
Dependent? 
Section 
Reference 


array 
(pR) LC II]<> 
for I#K: 
(op Y)CI] 


Table A-9 


(Cont.) 


Primitive Mixed Functions and Operators 
(Summary Information) 


dyadic dyadic 
expansion take (+) 
(\) 


R+X\CKIY R+«X+Y 


dyadic drop | monadic 


integers integers 
(0,1) 


scalar or 
vector 
(pX)<> ppy 


scalar or 
vector 


scalar or 
array 
dimension 


Same as 
right 
argument 


array 

(pR) LILI 
for I#K: 
(pY) CI] 
for IT=K:pX 


array 
oR<->|X 
ppR>ppY 


scalar or 
vector 


argument 


dyadic transpose 
(&) 


R«XQCKIY 


Same as right 
argument 


array 
(pk) CKI<+L/(K=X)/pY 


yes, left 
argument 





TI-W 





Table A-9 (Cont.) 
Primitive Mixed Functions and Operators 
(Summary Information) 


Function monadic dyadic monadic monadic monadic roll dyadic deal (7?) 
reverse (¢) | rotation |((¢)gradeup (4) grade down (Y)|(?) (primitive 


scalar) 
R+OLKIY R+XOLKIY R<ALKIY R+YLKIY R<?Y R+X?Y 
left 


integers non-negative 
Argument integer (X<Y) 
Domain 
right any any non-negative non-negative 
ee ae eee ee ee 
left scalar or scalar 
vector 


Argument 


Shape 
right Scalar or scalar or scalar or scalar or any scalar 
array array array array 
dimension dimension (ppY)<2 (ppY) <2 


Result same as same as characters characters or |non-negative non-negative 
Range argument right or numbers numbers integers (<Y) |integers (<Y) 
argument 
Result array array vector vector 
Shape pR++pY pR<pY pR++(pY) [KI] pRe (oY) [kK] 
Take 
Dimension 
Argument? 


Origin 
Dependent? 


Section 227615 2.7.16 
REference 


cT-W 


Table A-9 (Cont.) 
Primitive Mixed Functions and Operators 
(Summary Information) 


Function monadic quote dyadic encode dyadic decode monadic execute dyadic membership 
(T) (T) (4) (e) (e) 
R<«TY R<XTY R+«1Y R+eY 


left 
Argument 
Domain 

right 


left 
Argument 
Shape 

right 


Result null or characters or 
Range characters numbers 


Result array array pR<+> scalar or 
Shape vector oR<«>(pX),pY ( 149X),14pY array 
Take 

Dimension 

Argument? 


no 
Origin 
Dependent? no 


Section 
Reference 2.7.21 





€T-W 


Table A-9 (Cont.) 
Primitive Mixed Functions and Operators 
(Summary Information) 


Function i i i i dyadic dyadic subset | dyadic superset 
exclusion (c) (c) (>) (2) 
(~) 
R«X~Y R<«XcY R<XcCY | R«XDY R<X2>Y 


left any 
Argument 
Shape 

right 


Result characters characters 
Range or numbers or numbers 
Result vector 

Shape 

Take 

Dimension 

Argument? 

Origin 

Dependent? 

Section 2.7.26 

Reference 





*Both arguments must be either character or numeric; argument types cannot be mixed in the same function. 


vVI-W 





Table A-9 (Cont.) 
Primitive Mixed Functions and Operators 
(Summary Information) 


monadic format dyadic format monadic domino dyadic domino 
(F) (F) (BH) 
Function R<vY R<X¥Y R<«BY 
ea eae 


a 
scalar or array 
scalar or vector (ppX)<2 














left 
Argument 
Domain 

right 


scalar or array scalar or array 
(ppY)s2 (pp¥)<2 

Result 

Range characters characters numbers numbers 

Result array array array array 

Shape 1+pR+«> 140Y 1+pR+> 14pY pR+>+opY pR<>+(1+p¥),1+0X 

Take 

Dimension 

Argument? 

Origin 

Dependent? 


Section 
Reference 2.7.32 


ST-W 


Table A-9 


(Cont. ) 


Primitive Mixed Functions and Operators 
(Summary Information) 


monadic reduction 
(f/) 


Function R<f/CKIY 


Argument 

Domain 
same as for 
function f 


Argument 
Shape 


Result same as for same as for same as for 
Range function f function f functions f and g 


scalar if Y vector 
vector if Y vector 


oR+>+(k4#1ppX)/pY 
Take 


Dimension 
Argument? 


Section 
Reference 


monadic scan 
(f\) 
R<f\CRKIY 


same as for 
function f 


any 


array 
oR+>pY 


dyadic inner product 
(f.g) 
R<Xf.g¥ 


same as for 
functions f and g 


same as for 
functions f and g 


any 
any 


array 
pR<>( 14pX),14pY 


dyadic outer product 
(°.g) 
R<X0.gY 


same as for 
function g 


same as for 
function g 


same as for 
function g 


array 
pR<+>+(pY),pXx 





APPENDIX B 


APL SYSTEM COMMANDS 


This appendix contains an alphabetical summary of system commands 
available in APL-1l1. Definitions of the argument names included in 
the commands follow the command summary. In the command syntax models, 
parameters enclosed in square brackets ([]) are optional; the brackets 
themselves are not typed by the user. If two parameters are included 
in a stack and enclosed in brackets either of the two parameters may 
be selected. This is illustrated in the following format: 


0 
ORIGIN 1 


Command names and keywords included in the APL typeface should be 
typed without substitution, as indicated below. 


Command Meaning Section 
JASSIGN channel-number Assigns an existing file on the 6.3.1 
filename channel specified by channel- 
number. 
) CLEAR Replaces the active workspace 5.2.1 


with the clear workspace. 


JCLOSE channel-number Closes the file currently 6.3.2 
associated with the specified 
channel-number. 


JCOPY filename [named- Copies objects identified in the 5.3.6 
object-list] named-object-list from wsname 

into the current workspace. If 

the list is omitted, variables, 

functions, and groups are copied. 


)CREATE [ehannet- Creates a new file and allocates 6.3.3 
number] ftlename space for that file on the device 
associated with the ftlename. If 
channel-number is specified, the 
new file remains open for input; 
if it is omitted, the file is 
created and then closed. 


)DIGITS [(n] Displays or changes the number 5.4.2 
of significant digits displayed 
on output. The maximum number 
of digits for APZ-1l is 7 for 
single-precision systems and 
16 for double-precision systems. 
The defaults are 7 and 16 
respectively. 


B-1 


Command 


)DROP filename 


JERASE name-list 
JFNS (letter] 
)FUZZin] 


J)GROUP group-name 
[group-member-list] 


JGRP group-name 


JGRPS [letter] 


JLOAD filename 


)OFF 


1 


) ORIGIN [ "| 


)PCOPY filename [name- 
object-list] 


)JRUN filename 


APL SYSTEM COMMANDS 


Meaning 


Deletes the workspace filename 
from the user's disk area. 


Erases the objects identified 
in name-list from the active 
workspace. 


Displays an alphabetical list of 
function names in the current 
workspace. If letter is included, 
the list begins at the specified 
letter. 


Displays or changes the APL fuzz 
or comparison tolerance; n must 
be exponential and in the range 
0 through approximately .38. 


Collects named objects in the 
group-member-list into the group 
specified by the group-name. If 
the list is omitted, the group- 
name is dispersed. 


Lists the members of the group 
identified by the group-name. 


Displays an alphabetical list of 
group-names. If letter is 
included, the list begins at the 
specified letter. 


Retrieves a workspace from a 
secondary-storage device in 
core-image format. 


Terminates the current APL 
session, returning control to 
system command level (RT-11) or 
BASIC (RSTS/E). 


Displays or changes the index 
origin for the currently active 
workspace. The default origin 
setting is l. 


Copies objects identified in the 
named-object-list from wsname 

to the current workspace, protect- 
ing names already in use. If the 
list is omitted, all variables, 
functions and groups are copied. 


Terminates the current APL session, 
and runs the specified filename. 
The file specified in filename 
must contain a ready-to-run 
program. 


Section 


5.2.5 


5.5.2 


Command 


JSAVE [ftlename ] 


SI 


JSIV 


)VARS [letter] 


JWIDTH [n] 


JWSID Ufilename] 


Argument 


echannel-number 


filename 


group-name 


group-member-list 


APL SYSTEM COMMANDS 


Meaning Section 


Saves a copy of the currently active 5.203 
workspace on a secondary-storage 

device under the specified name in 

core-image format. If filename is 

omitted, the workspace is saved under 

the current name of the active 

workspace. 


Displays the workspace state indicator, 5.3.9 
which reports on the progress of func- 
tion execution. 


Displays the workspace state indicator, 5.3.10 
along with local variable names for all 
halted functions. 


Displays an alphabetical list of global 5.3.1 
variables in the currently active 

workspace. If letter is included, 

the list begins at the specified letter. 


Displays or changes the maximum width 5.4.3 
of the output line; m must be an 
integer in range 30 through 401. 
Displays or changes the name of the 56222 
currently active workspace. 

Meaning 
An integer in range 1 through 12 inclusive, 
specifying the channel on which the file being 
referenced is assigned. 
A standard filename in the following format: 


device:name.ext[stze] (for RT-11) 


device:name.ext<prot>([prj,prg1/SIZE: size 
/ CLUSTER: clus/MODE : mode (for RSTS/E) 


devtce:[Lutelname.ext;verston (for RSX-11M 
and IAS) 


All fields are optional and are described in 
detail in Section 5.1.3. 


An tdentifier that names a group of variables, 
functions, or other groups. 


A list of variables, functions, or group-names, 
separated by spaces. 





Argument 


tdentifter 


letter 


n 


name-list 


named-object-list 


number 


APL SYSTEM COMMANDS 


Meaning 
Any sequence of letters or numbers, beginning 
with a letter. Only the first 31 characters 
in an identifier are significant. 


One of the characters A-Z, A, or the underscored 
characters 4A-Z or A. 


An integer value. 


A list of identifiers that name variables 
and/or functions, separated by spaces. 


A list of identifiers that names variables, 
functions, and/or groups, separated by spaces. 


One of the digits, 0, 1, 2, 3, 4,5, 6, 7, 
8, 9. 


APPENDIX C 


SYSTEM VARIABLES AND I-BEAM FUNCTIONS 


This appendix contains a summary of the system variables and I-beam 
functions available in the APLZ-11 system. Those rI-beam functions 
that return meaningful information only in the RSTS/E operating 
environment are preceded by an asterisk (*). 


SYSTEM VARIABLES 
Variable Meaning Section 
May be reset by the user: 
Ocr Sets the degree of tolerance or relative fuzz 4.2.1 
to be applied in performing comparisons. Value 


must be in exponential form; the meaningful 
range is 0 through approximately .38. 


Oro Changes the setting of the index origin 4.2.2 
to 0 or l. 

OPP Sets the precision of non-integer output. 4.2.3 
Legal values are integers in range 1 through 
ye 

LIPW Sets the maximum number of characters that 4.2.4 


may appear in an output line. Legal values 
are integers in range 30 through 390. 


ORL Determines a link in the chain of random 4.2.5 
numbers used in the roll and deal functions. 


Retain system-specified values: 


OAV Stores a vector of all possible characters 4.2.6 
which can be expressed in the APL system. 


OLC Stores a vector of the line numbers in the 4.2.7 
APL workspace's state indicator, arranged 
in order of most recently suspended function 
first. 


OWA Determines the maximum amount that the active 4.2.8 
workspace may increase. 








SYSTEM VARIABLES AND I-BEAM FUNCTIONS 


I-BEAM FUNCTIONS 
I-Beam Meaning Section 


r15 Reinitializes error displays for the execute 4.3.1 
(e) function 


r16 Suppresses error displays for the execute 4.3.2 
function 
I17 Returns a two-element vector consisting of - 


the number of characters used so far in the 
symbol table and the number of characters 
remaining : 


118 Returns the condition of the active workspace: 4.3.3 
0 if intact, 1 if damaged 


r20 Returns the time from midnight in 60ths of a 4.3.4 
second (50ths in Europe) 


*I21 Returns the CPU time expended since user signed 4.3.5 
on in 60ths of a second (50ths in Europe) 


122 Returns the number of bytes available in the 4.3.6 
workspace 

*I23 Returns the system job number 4.3.6 

125 Returns today's date in form MMDDYY 4.3.7 

I26 Returns the line number of the statement about 4.3.8 
to be executed (first line number in the state 
indicator) 

I27 Returns a vector of line numbers in the state 4.3.9 
indicator 

I28 Returns the terminal character set: 0 if APL, 4.3.10 
1 if ASCII 

*I29 Returns the user's project-programmer number 4.3.11 

I30 Clears the state indicator 4.3.12 

133 Returns a vector representing the current 4.3.13 


workspace storage allocation 


134 Returns the APL precision: 0 for single- - 
precision, 1 for double-precision. 


136 Terminates the APL session; returns to system 4.3.14 
command level (RT-11) or BASIC (RSTS/E) 


139 Changes the current random number sequence = 


*RSTS/E only 


APPENDIX D 


ERROR MESSAGES 


If an error is detected during the evaluation of an APL expression, 
execution is normally interrupted. APL displays an appropriate error 
message from the list included below and outputs the line in which 
the error occurred. An up-arrow (+) identifies the approximate char- 
acter at which the error was detected, as shown in the following ex- 
ample. : 


L7+ (AL) x2 


VALUE ERROR 
17+ (AL) ee 
* 


If the execute (<) operator (Section 2.7.24) executes a string that con- 
tains an error, a null array of shape 0 # is returned as the value of 
the execute. F identifies the particular error condition that has oc- 
curred and is one of the numbers listed in this appendix. In addition 
to returning the null array, APL ordinarily displays the appropriate 
error message and error line that occurred as the result of the execute 
operation. However, if I-beam 16 (Section 4.3.2) has been issued, this 
display is suppressed. 


The execute error facility allows the APL-11 user to trap error condi- 
tions and often to handle these conditions under program control. In 
Many cases, it may be possible to resolve the condition without losing 
control and aborting function execution. The following is an example 
of a null array that indicates a value error in the command string: 
Note that 116 has been issued to suppress the error display. 

Zeg (Beat ' 


r= 
oil 
The meaning of possible error number values is summarized below. Note 
that some of these messages are warnings or status messages from APL 
(e.g., EXECUTION STOP), not actual error reports. 


These error messages are relevant to RT-11l and RSTS/E systems. APL 
users with RSX-11M or IAS systems should consult the IAS/R5xX-11 I/0 
operations reference manual for all system-defendent RSX-11M and IAS 
error conditions. 





Error 
Number 


2 


10 


ERROR MESSAGES 


Meaning/Explanation/Action 
SYSTEM ERROR 


Internal APL system error. If the problem can be reproduced, 
please report this error to Digital by submitting an SPR 
form, 


WS FULL 


There is insufficient space in the active workspace to hold 
the results of the most recent operation. Use 133 to obtain 
a storage allocation map. Try to )FRASE unnecessary vari- 
ables and functions, and clear the state indicator. 


SYMBOL TABLE FULL 


Too many different function and variable names have been 
defined in the active workspace. When this occurs there 
is also insufficient space in the active workspace, Try to 
JERASE unnecessary objects and clear the state indicator. 


DEFN ERROR 

Improper function definition. The syntax of the function 
header is incorrect, the function has already been defined 
in the workspace. 


LABEL ERROR 


Improper use of a colon or improper variable name used as a 
label. 


SYNTAX ERROR 


The statement is not a valid APL expression; invalid syntax 
has been detected - for example, two variables without an 
intervening operator, a function call with missing arguments, 
or an unmatched parenthesis. Alternately, function usage 
does not agree with the function type. 


INDEX ERROR 

An index value is out of range - for example, an expression 
is trying to reference a nonexistent array element, such as 
the tenth item of a nine-element vector. 

RANK ERROR 

The operation being attempted is not defined for arrays of 


that structure - for example, a scalar function is specified 
for nonconforming arrays. 


LENGTH ERROR 


The shapes of two arrays do not conform, or the operation 
being attempted is not defined for arrays of that length. 


Error 
Number 


11 


14 


15 


16 


21 


25 


26 


Pa 


34 


ERROR MESSAGES 


Meaning/Explanation/Action 
VALUE ERROR 
A value for a variable has not been previously assigned; all 
variables must be assigned values before they can be refer- 
enced in an expression. Alternately, a function with an 
explicit result did not return a value. 


DEPTH ERROR 


Function calls are nested to an excessive depth. Try to 
clear the state indicator. 


DOMAIN ERROR 

Division by zero was attempted, a negative number was 
included in a logarithm function, or both character and 
numeric arguments were included in a relational function, 
or the arguments of a primitive function are otherwise out 
of the function's domain (e.g., singular matrices for H). 
EXECUTION STOP 

A CTRL/C character was typed to interrupt function execution. 
COMMAND ERROR 

Unknown command or command that is improperly formed. 
CHARACTER ERROR 

Illegal character or overstrike combination. 

NOT YET IMPLEMENTED 

The requested function has not yet been implemented. If 
this message is returned when using matrix division or in- 
version (H), be sure that the matrix division functions 
(DMD and MMD) are present in the active workspace. 

SI DAMAGE 

An attempt has been made to edit a function that appears in 
the state indicator. It is usually recommended that the 
state indicator be cleared before functions are edited. 


BAD ERROR FOUND - THIS CALLS FOR AN SPR 


Internal error that should never occur. Please report this 
error to Digital by submitting an SPR form. 


RESTARTING APL 


The RT-11 RE command was used to reenter the APZ system. 


ERROR MESSAGES 


The error conditions listed below usually occur only in RSTS/E systems 
and are discussed fully in Appendix E of the RSTS/E PROGRAMMING MANUAL 
(DEC-11-ORPMA-A-D). If a message can occur in an RT-1l system, the 
wording of the message is included in the third column below. 


Error 
Number RSTS/E Version RT-11 Version 
51 BAD DIRECTORY FOR DEVICE 
52 ILLEGAL FILE NAME ILLEGAL FILE NAME 
53 ACCOUNT OR DEVICE IN USE 
54 NO ROOM FOR USER ON DEVICE DIRECTORY FULL 
55 CAN'T FIND FILE OR ACCOUNT FILE NOT FOUND 
56 NOT A VALID DEVICE DEVICE NOT FOUND 
57 I/O CHANNEL ALREADY OPEN CHANNEL ALREADY OPEN 
58 DEVICE NOT AVAILABLE DEVICE NOT AVAILABLE 
59 I/O CHANNEL NOT OPEN CHANNEL NOT OPEN 
60 PROTECTION VIOLATION 
61 END OF FILE ON DEVICE END OF FILE ON DEVICE 
62 FATAL SYSTEM I/O FAILURE I/O ERROR 
63 USER DATA ERROR ON DEVICE 
64 DEVICE HUNG OR WRITE LOCKED 
65 KEYBOARD WAIT EXHAUSTED 
66 NAME OR ACCOUNT NOW EXISTS 
67 TOO MANY OPEN FILES ON UNIT 
68 ILLEGAL SYS () USAGE 
69 DISK BLOCK IS INTERLOCKED 
70 PACK ID'S DON'T MATCH 
71 DISK PACK IS NOT MOUNTED 
72 DISK PACK IS LOCKED OUT 
73 ILLEGAL CLUSTER SIZE 
74 DISK PACK IS PRIVATE 
75 DISK PACK NEEDS 'CLEANING' 
76 FATAL DISK PACK MOUNT ERROR 
77 I/O TO DETACHED KEYBOARD 
78 PROGRAMMABLE +C TRAP 
79 CORRUPTED FILE STRUCTURE 
80 DEVICE NOT FILE STRUCTURED 
81 ILLEGAL BYTE COUNT FOR I/O 
82 NO ROOM AVAILABLE FOR FCB 
83 UNIBUS TIMEOUT FATAL TRAP 
84 RESERVED INSTRUCTION TRAP RESERVED INSTRUCTION TRAP 
85 MEMORY MANAGEMENT VIOLATION 
86 SP (R6) STACK OVERFLOW 
87 DISK ERROR DURING SWAP 
88 MEMORY PARITY FAILURE 
89 MAGTAPE SELECT ERROR 
90 MAGTAPE RECORD LENGTH ERROR 
91 WO RUN-TIME SYSTEM 
106 ILLEGAL I/O CHANNEL ILLEGAL CHANNEL NUMBER 
107 LINE TOO LONG LINE TOO LONG 
108 FLOATING POINT ERROR 


APPENDIX E 


APL INSTALLATION PROCEDURES 


This appendix describes the procedures for installing APL in the 
user's system. It discusses the configuration options available to 
users of APL-11 and illustrates methods for installing the system in 
the RT-11, RSTS/E, RSX-11M, and IAS operating systems. 


APL INSTALLATION PROCEDURES 


E.1 INSTALLING APL IN AN RT-11V3 SYSTEM 


The following procedures are used to install APLZ-11 in the RT-11 
operating system. In this example, the APLO0.SAV file on DKO 
is copied to APL.SAV on DKl. 


»COPY TIKI ZAFLOO.SAY AFL. SAY 


The user can subsequently invoke the APL system by typing: 
+R AFL 


and answering the TERMINAL . . query as described in Section 1.4.1. 


E.2 INSTALLING APL IN A RSTS/E V6C SYSTEM 


The following procedures are used to install APZ-11 in the RSTS/E 
operating system. APLxex represents the distribution version number 
of the installation's configured copy of APZ-11, and dev is the 
device on which APL is found (e.g. DKl:). Before running PIP, the 
user logs onto RSTS/E in the normal way, specifying a privileged 
account (i.e., any ppn of the form [1,n]). Text typed by the user 
is underlined in the example that follows. 


APL INSTALLATION PROCEDURES 


OLD dev: [1,2]APL.BAS 
COMPILE [1,2]APL 


RUN PIPS 

#([0,1]APL.*MODE:16 = dev: [0,1]APLnn.RTS 
#[1,2]APLCLR.APC = dev: [1,2]APLCnn.APC 
[0,1J]APL.RTS<60>/RE 
[1,2]APLCLR.APC<40>/RE 
{1,2]APL.BAC<104>/RE 


> 
Nil i ou 


[ae|4#14=]44] 


RUN SUTILTY 
*ADD APL 
*EXIT 


Be sure to add the "ADD APL" statement to the [1,2]RTS.CMD file, in 
order to insure that APZ will be automatically installed when the 
system starts up. 





Action commands, 5-2 


Active workspace, 1-2, 5-2, 5-3, 


Add 


5-6, 5-7, 5-8 
(+) function, 2-19 


Adding function lines, 4-6 


APL 


APL 
APL 
APL 
APL 


APL 
APL 


character set, 1-5 through 
1-7 

data files, 1-3 

hardware, 1-3 

keyboard, 1-4 

operations, returning pre- 
cision of, 3-6, 3-7 
operators, A-1l through A-7 
statements, 


evaluation of, 2-7 
overview, 2-1 
types, 2-6 

Arrays, 2-3, 2-4, 2-5 
catenation of, 2-29 through 


2-32 


compressing, 2-38, 2-39 


computing the inner product, 
2-35, 2-36, 2-37 

computing the outer product, 
2-37, 2-38 

conformability rules, 2-36 

converting a value, 2-29 

dealing random integers, 2-53 

decoding, 2-51, 2-52 

determining the members, 2-56 

dropping elements, 2-41, 2-42 

expanding, 2-39, 2-40 

finding the index of a value, 
2-27, 2-28 

generating consecutive integers, 
2-26, 2-27 

indexing, 2-10, 2-11, 2-12 

inverting, 2-58 

lamination of, 2-29 through 
2-32 

output, heterogeneous, 2-17 

reducing, 2-33, 2-34 

replacing values, 2-12 

representing in another base, 
2-50, 2-51 

reshaping, 2-25, 2-26 

returning the shape, 2-22, 
2-24 

reversing, 2-45, 2-46 

rolling random integers, 2-53 

rotating, 2-46, 2-47 

sorting in ascending order, 
2-47, 2-48, 2-49 
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2-49 
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Arrays (cont.), 
taking elements, 2-40, 2-41 
transposing, 2-43, 2-44, 2-45 
Arrow left («) in assignment, 


2-6 

Arrow right (+) in branching, 
4-12, 4-13 

ASCII/APL terminal, 1-3 through 
1-7 


Assigning a file, 6-10 

Assignment statements, 2-6, 2-17 

Associating channel number, 6-5, 
6-6, 6-7, 6-10, 6-11 


Backspacing, APL, 1-12 

Base, representing a number in 
another, 2-50, 2-51 

Base value function, 2-51, 2-52 

Binomial coefficient (!), 2-23 

Blanks, inserting in a function, 
4-9, 4-10 

Boolean vector, 2-39, 2-40 

Brackets (subscripts), 2-10, 
2-11 

Branch statements, 2-6, 2-17 


Caret (*) error indicator, 1-9 
1-11 
Catenating (,) function, 2-29 
through 2-32 
difference from lamination, 
2-31 
Ceiling ([) function, 2-18, 2-19 
Changing, 
fuzz, 2-13 
index origin, 2-12, 5-12 
output precision, 5-12, 5-13 
width of output, 5-13 
workspace name, 5-6 
Channel number, 6-4 through 
6-15 
Character set, APL and ASCII, 
1-5, 1-6, 1-7 
Character set, returning termi- 
nal, 3-5 
Character string, 
converted to by quote, 2-56, 
2-57 
evaluated by execute, 2-53, 
2-54, 2-55 
Character vector, 2-4 


Index-1l 
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Characters, 
editing, 1-13, 1-14 
errors, 1-12, 1-14 
terminal control, 1-8, 1-9 
Circle functions, table of, 2-20 
Clear workspace, 5-6 
Closing a file, 6-11 
Colon (:) in statement labeling, 
4-13 
Comma (,), in ASCII mode, 1-4 
in dyadic catenation or 
lamination, 2-29 through 
2-32 
in monadic ravel, 2-29 
Comment character (a), 4-4 
Comments, 2-5, 2-6 
Comparison tolerance, 2-13, 5-13, 
5-14 
(see also "fuzz") 
Compression (/) function, 2-23, 
2-38, 2-39 
Compression (4) along first 
coordinate, 2-39 
Conditional branches, 4-12, 4-13 
Conformability rules for arrays, 
2-36 
Connecting with APL, 1-7 through 
1-11 
Constants, 2-2, 2-3 
Control characters, 
CTRL/C, 1-8, 1-9, 1-11, 1-12, 
1-13, 2-17 
CTRL/O, 1-8, 1-11, 2-17 
CTRL/U, 1-12, 1-13 
CTRL/Z, 6-2, 6-6 
Correcting APL text, 
after entry, by editing, 1-12, 
1-13, 1-14, 4-6, 4-9 
before entry, by backspacing, 
1-12 
by LINE FEED, 1-14 
CPU time, returning, 3-3, 3-4 
Creating a file, 6-10, 6-11 


Data structures, 2-3 

Data types, APL-11l, 6-3 

Date, returning today's, 3-4 

Deal (?) function, 2-53 

Decode (1) function, 2-51, 2-52 

DECtape, 1-2, 1-3, 5-7, 5-8, 
6-1 

Definition functions, 4-1, 4-2 

Del (V) shifting modes, 4-1, 
4-2 

Del, locking functions, 4-18 

Deleting a function line, 4-7 


Deleting workspaces, 5-8 
Determining comparison tolerance, 
5-13, 5-14 
Determining index origin, 5-12 
Determining output precision, 
5-12, 5-13 
Determining width of output line, 
5-13 
Disk, 1-2, 1-3, 5-7, 5-8, 6-1 
Displaying a function line, 4-8 
through 4-11 
Displaying functions, 5-9, 5-10 
Displaying state indicator, 
5-10, 5-11 
Displaying variables, 
global, 5-9 
local, 5-11 
Displaying workspace name, 5-6 
Divide (+) function, 2-19 
Division function, matrices, 


2-59, 2-60 
Domino (fH) function, 2-58, 2-59, 
2-60 


Drop (+) function, 2-41, 2-42 

Dummy variables, 4-3 

Dyadic functions, 2-18, 4-2, 4-5 
tables of, 2-19, 2-20 

Dynamic localization, 4-3, 4-4 


(e) (exponentiation), 2-19, 

Editing function headers, 4- 

Editing function lines, 4-5 

through 4-11 
Editing procedures, 
immediate-mode, 1-12, 1-13, 

1-14 

Encode (tT) function, 2-50, 2-51 

Ending the APL session, 1-8 
through 1-11 

Erase (A) character, 4-7 

Error, characters, 1-12, 1-14 

Error handling, 2-9, D-1 through 
D-5 

Errors, function-execution mode, 
2-9, 2-53, 2-54, 3-2, 3-3 

Errors, immediate-mode, 2-9 

Errors, table of messages, D-l 
through D-5 

Escaping from an input loop, 
2-16 

Evaluated input, 2-14 

Evaluation of APL statements, 
2-7 

Execute (e« or 1) function, 2-53, 
2-54, 2-55, 5-11, 5-15, 5-16 

Execution mode, 4-1 


2-20 
9 


Index-2 


INDEX 


Expansion (\) function, 2-39, 
Expansion along first coordi- 
nate, (*), 2-40 
Exponentiation (e), 2-19, 2-20 
Factorial (2) function, 2-19 


File, 
ASCII sequential, 1-3, 6-1, 
6-2, 6-3 


assigning, 6-10 
closing, 6-11 
creating a direct-access, 6-10, 
6-11 
data, 1-3 
input mode for ASCII sequen- 
tial, 6-6, 6-12 
input operator (Mf), 2-14, 6-6 
names, 5-3, 5-4, 5-5 
output operator (f), 2-14, 
6-7 
pointer (#8), 6-4 through 6-7 
random access, 1-3, 6-2, 6-3 
reading, 6-12 through 6-15 
renaming, 6-12 
sequential, 6-1, 6-2, 6-3 
system, 6-1 through 6-15 
types, 6-1 
writing objects to, 6-14, 6-15 
Filename components, 5-4, 5=5 
Filename format, 6-9 
Floating point numbers, 1-1, 
2-7, 6-6 
Floor (L) function, 2-8, 2-19 
Formatting numeric output, 2-7, 
2-8 
Function body, 4-1, 4-2 
Function defining in quad input 
mode, 4-4 
Function header, 4-1, 4-2 
editing the, 4-9 
Function line, displaying, 4-8 
through 4-11 
Function summary tables, A-1 
through A-7 
Function, 
adding a line, 4-6, 4-7 
body, 4-1, 4-2 
branching, 4-12, 4-13 
definition mode, 4-1 through 
4-8 
deleting lines, 4-7 
displaying lines, 4-8 
dyadic, 4-5 
editing, 4-5 through 4-11 
editing the function header, 
4-9 
encode, 2-50, 2-51 
executing, 4-11 through 4-18 


(CONT. ) 


Function (cont.), 
header, 4-1, 4-2 
immediate line editing, 4-9, 
4-10, 4-11 
input, 4-4 
inserting lines, 4-7 
line editing, 4-9, 4-10, 4-11 
line numbers in, 4-5 through 
4-11 
locking, 4 
monadic, 4 
niladic, 4- 
opening, 4- 
output, 4-4 
pendent, 4-14, 5-11 
renumbering, 4-9 
replacing lines, 4-6, 4-7 
suspended, 4-14, 5-11 
Functions, displaying a list, 
5-9, 5-10 
Fuzz, 2-3, 5-13, 5-14 
(see also Comparison toler- 
ance) 


Global variables, 4-3, 4-4 

Grade down (VY) function, 2-49 

Grade up (A) function, 2-47, 
2-48, 2-49 


H (for HELP), 1-7 


I-beam system functions, 
table of, C-1, C-2 
I-beams, 3-1 through 3-9 
Identifiers, 2-2 
Identifying the active workspace, 
5-6 


Identity elements, table of, 
2-34 
Identity (+) function, 2-19 
Immediate mode, 4-1 
Immediate-mode editing procedures, 
1-12, 1-13, 1-14 
Index (1) function, 2-27, 2-28 
Index generator (1), 2-26, 2-27 
Index origin, 2-12, 5-12 
Indexing arrays, 2-10, 2-ll, 2-12 
Inner product definitions, 2-37 
Inner product (f.g) function, 
2-35, 2-36, 2-37 
Input loop, escaping from an, 
2-16 


Index-3 
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Input, 2-14 
evaluated (0), 2-14 
operators, 2-14 
overview of, 2-13 
prompt signal, 2-14 
quad (0), 2-13, 2-14, 2-15 
quad-del (M), 2-15, 2-16 
quote-quad (MN), 2-15 
to file, 6-4, 6-7, 6-14, 6-15 
Inserting a function line, 4-7 
Interrupting APL, 1-8, 1-9, 1-11 
Inquiry commands, 5-2 
Inversion function, matrices, 
2-58 
Tota (1) function, 2-26, 2-27, 
2-28 


Job number, returning system, 
3-4 


Keyboard, APL, 1-4 


Labels, statement, 4-13 
Lamination (,) function, 2-29 
through 2-32 
difference from catenation, 
2-31 
Least squares solution, 2-59, 
2-60 
LINE FEED, 1-13, 1-14 
Line length (APL), 1-12 
Line number, returning, 3-4 
Line numbers, 
in functions, 4-5 through 4-11 
returning vector of, 3-5 
Literal vector, 2-4 
Local variables, 4-3, 5-11 
Locking a function, 4-18 
Log base N (*), 2-19 
Logarithm, 2-19 


Magnetic tape, 1-2, 1-3, 5-7, 
5-8, 6-1 

Magnitude (|), 2-18, 2-19 
Matrices, 2-4 
Matrix division function, 2-59 
Maximum of ([), 2-19 
Membership (<«) function, 2-56 
Minimum of (L), 2-19 
Mixed functions, 

overview of, 2-22 

table of, 2-23 


Monadic functions, 2-18, 2-19, 
4-2, 4-5 
Multiply (x) function, 2-19 


Natural logarithm (@), 2-19 
Negative numbers, 2-3 
Negative sign (-), 2-3 
Niladic functions, 4-2, 4-4, 4-5 
Normal output (0), 2-16, 2-17 
Numbers, 2-2, 2-3 
Numeric constants, 2-2 
Numeric representation, 2-7, 

2-8 


O(ASCII, OU) escape character, 
1-13, 1-14, 2-16, 4-4 
Operators, table of, A-1l through 
A-7 
Operator precedence, 2-7 
Outer product definitions, 2-38 
Outer product (°,f) function, 
2-37, 2-38 
Output, 2-16 
bare (M or M), 2-15, 2-16 
heterogeneous, 2-17 
normal, 2-16 
operators, 2-14 
overview of, 2-13 
quad, 2-13, 2-16, 2-17 
terminating, 2-17 
width-determining, 5-13 
Overstruck characters, creating, 
1-5 


wm times (0), 2-19 
Parentheses, in evaluation, 2-7 
Parentheses, right, in system 
commands, 5-2 
Pendent functions, 4-14, 5-11 
Period typed by the system, 1-7 
PIP command, 1-9 
Precision, 
of numbers, 1-2, 2-7 
output, 5-12, 5-13 
Primitive scalar functions, 2-18 
through 2-22 
table of, 2-19 
Primitive mixed functions, 2-22 
table of, 2-23 
Program, running a, 5-14, 5-15 
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Quad (0) character, 2-13 through 
2-17, 4-8, 4-9, 4-10 
as input prompt, 2-14, 2-15 
indicating pending input 
requests, 4-14, 4-15 
Quad (evaluated) input (+f), 
Quad output (f+), 2-14 
Quad-del operator (M), input 
mode, 2-15, 2-16 
Quad-del (unedited) input (+), 
2-14 
Quote (T) function, 2-56, 2-57 
Quote character, 2-14 
Quote-quad (character) input 
(+0), 2-14 
Quote-quad operator (fM), input 
mode, 2-15 


RSTS/E, 1-10, 1-11, 5-3, 5-4, 
5-13, 5-14, 5-15, 6-1, 6-9 
RT-11, 1-7, 1-8, 1-9, 5-3, 5-4, 
5-13, 5-14, 5-15, 6-1, 6-9, 
6-11 
Random-access files, 1-3, 6-2, 
6-3 
Random integer (?), 2-19 
Random selection, 
in deal function, 2-53 
in roll function, 2-53 
Ravel (,) function, 2-29 
Reading a file, 6-12 through 
6-15 
Reading data from a file, 6-6 
Reciprocal (+) function, 2-19 
Reduction (f/) function, 2-33, 
2-34 
Reduction along first coordi- 
nate (4), 2-34 
Reenter command, 1-9 
Relational functions, 
arguments to, 2-21 
fuzz, 2-13, 5-13, 5-14 
Renaming a file, 6-12 
Renumbering a function line, 
4-9 


Replacing a function line, 4-6, 4-7 


Replacing values in arrays, 


2-12 

Representation function, 2-50, 
2-51 

Residue (|) function, 2-18, 2-19, 
2-21, 2-22 


Reshape (p), 2-25, 2-26 
Resuming APL operations, 1-8, 
1-9 


Retrieving a workspace, 5-8 

RETURN key, 1-7, 1-10, 1-12, 
1-13 

Returning to command level, 1-8, 
1-9 

Reverse (6) function, 2-45 

Reverse along first coordinate 
(9), 2-46 

Rho (9) function, 2-4, 2-22, 
2-24, 2-25, 2-26 

Roll (?) function, 2-53 

Rotate (%) function, 2-46, 2-47 

Rotate along first coordinate 
(fd), 2-47 

RUBOUT, 1-12, 1-13 

Running a program, 5-14, 5-15 


Saved workspace, 1-2, 5-3, 5-7, 
5-8, 6-2, 6-15 
Scalar functions, 
extension to arrays, 2-18, 
2-20 
overview of, 2-18 
table of, 2-19, 2-20 
Scalars, 2-3 
Semicolon (;), 
in array dimension specifica- 


tion, 2-11 

in heterogeneous output, 2-14, 
2-17 

in local variable specifica- 
tion, 4-3 


Sequential files, 6-1, 6-2, 6-3 
Session, ending the APL, 1-8 
through 1-11 
Shift characters, 1-5 
Sign-on greeting, 1-7, 1-8, 1-10 
Signum (x) function, 2-19 
Slash (/), 
compression, 2-38, 2-39 
in line editing, 4-9 
reduction, 2-33, 2-34 
Sorting an array, 
ascending order (grade up) 
(A), 2-47, 2-48, 2-49 
descending order (grade down) 
(Y), 2-49 
Spaces, 2-5 
Specification statements, 2-6 
Specifications, multiple, 2-6 
State indicator, 5-10, 5-11 
clearing the, 3-6 
Statement components, APL, 2-2 
execution modes, 2-1 
(immediate-mode, 2-1) 
(function-definition mode, 2-1) 
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Statement components, APL (cont.), 
labeling, 4-13 
types, 2-6 
(branch statements, 2-6) 
(assignment statements, 2-6) 
Statements, evaluation of APL, 
2-7 
Stop vector, 4-17 
Subscripts, 2-10, 2-11 
Subtract (-) function, 2-19 
Suspended functions, 4-14, 5-11 
Symbol table information, 
returning, 3-3 
System commands, format of, 5-2 
overview of, 5-1 
table of, B-1 through B-4 
used with execute function, 
5-15, 5-16 
System commands, 
JASSIGN, 6-10 
)CLEAR, 5-6 
)CLOSE, 6-11 
J)CREATE, 6-10, 6-11 
JDIGITS, 5-12, 5-13 
)DROP, 5-8 
JERASE, 5-10 
JFNS, 5-9, 5-10 
)FUZZ, 5-13, 5-14 
J)LOAD, 5-8 
JOFF, 5-14 
JORIGIN, 5-12 
JREAD, 6-12, 6-13 
)RENAME, 6-12 
JRUN, 5-14, 5-15 
JSAVE, 5-7 
JSI, 5-10, 5-11 
JSIV, 5-11 
)VARS, 5-9 
JWIDTH, 5-13 
JWRITE, 6-14, 6-15 
JWSID, 5-6 
System job number, returning, 3-4 


Take (+) function, 2-40, 2-41 
Terminals, 1-3, 1-4 
control characters, 1-8, 1-9, 


1-11 
prompt, 1-7 
Terminal character set, returning, 
3-5 


Terminating APL sessions, 1-8, 
1-10, 5-14, 5-15 


Terminating output, 2-17 

Time, returning CPU, 3-3, 3-4 

Time of day, returning, 3-3 

Today's date, returning, 3-4 

Tolerance comparison, 2-13, 5-13, 
5-14, (see also "fuzz") 

Trace vector, 4-15, 4-16 

Transpose (¢) function, 2-43, 
2-44 

Transpose, table of definitions, 
2-45 


Unquote (ce) function, 2-53, 
2-54, 2-55 

Up-arrow (+) error indicator, 
1-9, 1-11, 2-9 

User's project-programmer 
number, returning, 3-5 


Variables, 2-2 
classification of, 4-3 
displaying a list, 5-9, 5-11 
dummy, 4-3 
erasing, 5-10 
global, 4-3 
local, 4-3 

Vectors, 2-4, 2-37, 2-38 
indexing, 2-10, 2-11, 2-12 
reducing, 2-33, 2-34 

Vector of line numbers, return- 

ing, 3-5 


Width, determining of output 
line, 5-13 
Workspace, 1-2 
active, 5-2, 5-3 
clear, 1-2, 5-5, 5-6 
deleting, 5-8 
loading, 5-8 
names, 5-2, 5-3, 5-6 
returning condition of, 3-3 
saving, 1-2, 1-8, 1-9, 1-11, 
5-3, 5-7, 5-8, 6-2, 6-15 
size, 1-1, 1-2, 1-3 
Workspace name displaying, 5-2, 
5-3, 5-6 
Writing data into a file, 6-7 
Writing objects into a file, 6-14, 
6-15 
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